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CHAPTER 1 


INTROOUCING the OPERATING SYSTEM (TOS) 


The addition of disk drives to the SPECTRUM creates an innensely 
powerful systems and TOS - the disk operating system especially 
developed - gives you the power from within your BASIC 
programne that you have aluays wanteds but never believed would be 
available. 


The secret lies in the controller whichs controls the operation of 
the disk drivess and it is here that the TOS opersting systes 
resides. The controller is a separate computer having its own 
ZB80A Central Processors ss well as its own internal semory and 
input output facilities. Every time a TOS command is issued it 
passes straight to the controllers which then executes the 
instructions placing no overhead on the SPECTRUM? and of course is 
not dependent on any hardware limitations of the SPECTRUM: such as 
available menory. 


The disks are the lastest in micro floppies: using very high 
density recording medivers giving on the standard floppy 160K free 
on each side of the disk providing 320K of disk space per drive. 


The controller and TOS have been especially designed around the 
need to communicate. The controller has two serial comaunication 
ports which can be be configured to suit almost any type of 
protocol you sre likely to need. This aeans that apart from being 
able to comaunicate with TOS users» you will be set to ‘talk’ to 
other users, on s variety of coaputers with e standard RS§232C 
serial’ port. Other peripherals such as aodeasr printers, plotters 
or any device that can be coupled to s serisl port can seiso be 
connected to these. 


ABOUT THIS MANUAL 


The manual has three separ ste sections. 


The first conteins enovgh information for you to set up and begin 
working with TOs. 


The second goes through some of the aore subtle ways of applying 
TOS in relation to the use of tree directory structures, randos 
eccess and sequential files» end concludes with a chapter on the 
vse of channels and serial comaunication ports. 


The third part is 3 series of appendices for more specialised 
references and a quick reference guide to TOS. 

Inforaation asbout the utility progranmaes included on your deao 
disk are explained in this section. 


CHAPTER 2 


UNPACKING AND SETTING UP 


Unpacking your system you will find! Disk drive unit * 
Controller 
Power supply 
Manval 
Diskette 


Set up the systea es follows? 

-Switch the power OFF to your SPECTRUM coaputer. 

-Plug the interface into the rear edge-connector of the SPECTRUM. 

-Connect the 'D' plug of the controller to the interface. 

-Connect the ribbon cable from the controller onto the disk drive. 
There is a white sark on the ribbon plug which should be 
pointing upwards: placing the red edge of the cable on your 
left as vou look st the socket. The plug st the end of the 
ceble aust slusys be connected to disk A. 

“Connect the power supply up as follows! 

Check that the ON/OFF switch st the rear is off ‘0° 
Plug the power leads into the disk drive and controller. 
Connect the aains plug. 

-Before turning on and inserting your diskette please read the 

section ‘about the diskettes’. 

-If you sre using aore than one disk drive refer to the section 


, following an ‘Expanding the systena'. 


If you sre using a printer that noraslly plugs onto the SPECTRUM 
tear edge-connector you will need to connect the optional '‘T' 
connector between your SPECTRUM and the interface. The interface 
uses sll the address lines on the port and needs to have sore 
lines than sre available from plugging into the back of the nornal 
printer connecting plug. 


If your are using a printer that has a standard RSZ32C interfacer 
it easy be connected to one of the two serial comaunications ports 
on the controllers using 2 lesd with the sppropriste end 
connectors. Such lesds sre available to plug into the 
controller. Inforestion is contained sbovt RS232C interface 
connections in the relevant sppendix of this manual. 


a 
ABOUT THE DISKETTES 

nn ee SS Ss Sees 
The diskettes are made of a flexible mylar sheet coated with 
magnetic materials and are enclosed in a plastic casings which has 
a shutter to protect the recording media. This shutter is 
automatically opened when the disk is inserted in the drives and 
is the point where the read/write head of the disk drive is 
positioned. The disks have two sides» and sre double densitys and 
when used with this system have s formatted (meaning usable) 
capacity of 160K per sider giving in 811 320K per drive. 


The disks are very reliables but some basic precautions use aust 
be taken 3 
-Do not expose the disks to heat or direct sunlight. 
~Keep away from strong aagnetic fields»e.g transformers. 
-Do not open the shutter or finger the asgnetic surface, 
-Keep susy dust that could reach the recording surface. 


The disks can be write protected by using the small plastic tabs. 
You can protect either side A or B or both by switching the two 
tabs on the disk. The crestion of a hole by aoving the tab will 
write protect the relevent side of the disk. Where the tab blanks 
off this hole the disk is not write protected, 
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2.3 EXPANDING THE SYSTEM 


caer 
The basic configuration with a single disk drive can be. upgraded 
to a total of four disk drives! ArBrCrd. The first one is A and 
each additional drive is assigned o letter as far as D. 


Using more than two drives neccesitates the use of a second power 
supply and a second cable from the controller to the drives. 


The initialisation of the disk drives from the factory is for use 
as A drive. You will need to configure further disk drives 
yourselfs as BrCr or Dr depending an your systea. You do this as 
follows: 

-Unscrew the 4 screws on the base of case which hold the drive 
asseably in position. Remove the drive asseably from the 
case. The blue capped IC (integrated circuit) in a socket 
near the edge-connector of the drive marked R1 is only needed 
in drive @» for other drives it has to be reaoved. There is 
a juaper marked J01 which has to be connected corresponding 
to the drive designation using the following valuest 
A=0»B212C=22023. As you configure a new drive renesber to 
label it with the drive letter on the front to the drive for 
easy identification. From the outside of the drive you can 
check the designation by looking into the rear edge 
connector. Under the word ‘interface’ you will see the seall 
connector in ane of 4 positionss the leftmost position 
corresponds to Ar and the right hand pins for 0. 


Figure 1. 


If you are in doubt or difficulty contact your dealer. 


CHAPTER 3 


USING TOS COMMANDS 


The wey of sccessing the TOS commands is familiar to those used to 
the SPECTRUM BASIC’s use of keywords. All the TOS commands use 
existing keywords, but they are followed by an = (asterisk)» so 
that LOAD becomes LOAD z. 


TOS is # disk operating system! TOS commands sre designed so that 
you can LOAD and SAVE with the Disk Drives in a way similar to 
thet of cassettes. 


The beauty of TOS is that it does not interfere with the existing 

instructions relative to the cassette, so that you are still free. 
to use your cassette snd disk drives at the same timer and even 

from within the same programme: You need not change your existing 

progremees when using TOSe but you will need to use LOAD = and 

SAVE = to transfer the progranmes to and from the disks (in much 

the saee way you would for a cassette). The syntax is essentially 

the sape spart froe the ‘'R's which is there to activate TOS. 


Instructions can either be executed directly from the keyboard or 
from within the programme like any other BASIC instruction. TOS 
therefore becomes an extension of the SPECTRUM BASICs with a11 the 
disk and file handling facilities of TOS acting es extended BASIC 
functions. 


The next section desls with the TOS instructions. There sre two 
wave instructions can be executed: either directly froma the 
keyboard (referred to ss commands)» or from within @ progrenae 
(referted to as statements). Throughout the manual - in relation 
to TOS - the teres coseend and statenent will be used in this 
context. 

The tere ‘file’ includes all types of progrsmnes end date files» 
and no special distinction is made unless spplicable. 


Knowledge of the SPECTRUM keyboard and SPECTRUM BASIC is sssuned. 
Any doubts may be clarified by referring to the SPECTRUM manual. 


GETTING STARTED 

hes seen 
The disk thet cones with the system contains the denonstration 
programees on side A and side B has nothing on it. If you look at 
the disk you will see that side A has been write protected using 
the plastic tab. Side B is not write protected: and is for you to 
vse. The only copy of TOS vou have is on side As so aske sure 
that the disk remains write protected. Side B will have to be 
Formatted to be useds and is explained in section 3.4. 


With the system set up you can now switch on the current using the 
power switch on the back of the power supply in the ‘1° position. 


Insert the disk labelled TOS in the drive and the systee will 
‘soot’. The red light on the drive will flicker until finally it 
goes off. TOS is then ready for use. There is the controller 
reset buttons which resets the whole systea or the reset button on 
the interfaces to reset the SPECTRUM. 


hen vou reset the controller TOS will be ‘BOOTED’. There will not 
be the norasl nessege on the screen that sppears when you turn on 
the SPECTRUM by itself when not using TOS. 


There is a special kind of boot sdescribed in section 3.15 sthat 
allows the sutomatic execution of se start up progrease on your 
SPECTRUA. 


CAUTION 

Do not power up the system with the disk inserted in the drive. 
If you stack the systems the power supply should be on the top . 
Never prevent sir circulation to the power supply. 
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CAT = ~catalogue disk directory contents 

Unless a cassette is labelled properly there is no way of knowing 
what programmes it contains without loading the programmes into 
the coeputer. TOS has a special directory of each file on the 
disks together with information about where it is located on the 
disks the size of the files and other informations sone of which 
is useful only to the operating system, but some of which is 
Gisplayed as part of the listing appearing on the screen as a 
result of executing the CAT & instruction, 


Using side A of your devo disk type in the compand!( Side A is 
accessed by placing the disk into the drive door with side A 
facing upwards) 

CAT & followed by enter 


A listing of the disk directory contents will appear. Notice that . 
you can stop the SCROLLING at any tise using the S key and resune 
using the @ key. Try it. ‘This is common to many TOS commands, © 


{DEMO 

Level © Orive A 

None Typ Size Alloc Ss P 
HELP BAS 11087 1ik P 
MATHS DIR 3187 aK P 
FUN DIR 6651 9K P 
UTIL OIR 3075 7K P 
FILING DIR 1070 2K P 
MAX 140K CUR 33K REM 107K 

0 OKe O81 


rr Ps Spite epee 
FILENAMES -what is in a filenase 
SPS 
Referring the directory output from the CAT = instruction of the 
previous pager you will see the coluans contain the filenames the 
extension (type) of files the file size in bytes» the disk 
allocation and finally two coluans headed & and P» these are to 
indicate if the file is currently open» and if it is write 
protected. 


The filename is a string of up to 8 characters: optionally 
followed by another string of up to 3 characters to indicate the 
file type. The filename and the extension aust be seperated by a 
(dot). TOS treats the filename as a BASIC string and therefore 
it peust be surrounded by aatching quotes. It is possible to use 
svabols as well as digits and characters, although the syabol aust 
be a single character not >= or keywords, The following svabols 
are used by TOS and must not be used? °.°57°S*s°P%n%e*, 


TOS will automatically convert any file nase to the upper case 
equivalent 


Exaeples? 
“HELP.BAS® equivalent tot “hElp.Bas® or “help.bas* | 
*UTILITY.OIR® 


The file type is useful for references the only extensions that 
have special aeaning to TOS are the DIR and SCP extensions» used 
to identify the name of a directory or 8 comaunication channel. 
TOS stores files in directories: but also allows a directory to 
be stored within another directory. The route to a file or the 
pathnamer may be just the name of the filer but can include the 
heme of the directories on the route to the file. Being able to 
specify pathnames in this way is s very powerful feature of TOS» 
and a chapter of the manual is devoted to it. 

The size of the file is the number of bytes the prograeme will use 
in RAM (Randoa Access Hesory) of the SPECTRUM plus S or 7 bytes 
for use of the systea. 


The disk is divided into tracks: which are in turn divided into 
sectors. These tracks and sectors are termed ‘soft sectored's 
because they are written to the disk by software. This process of 
Placing these tracks and sectors on the disk is called Formattingr 
and aust be done before the disk can be used. 


The disk allocation of a file relates to the number of sectors 
used. TOS allocates always s miniaum of 1KB(1024 bytes) to a file. 


The last two coluans headed §& & P indicate whether the file is 
opens and whether or not it is write protected. 

Open meanings that the file is currently open to be sccessed from 
a prograeme. The P indicates that a file is write protectedr this 
refers to the software facility within TOS, not the setting of the 
plastic tab on the casing of the disk. 


AAPA ER A TP SR SPO, ME I PSAP SS RAS SEPM BE LEE DE NEEL SEE TEED EE EE: ET 
FORMAT & -prepare new disk to operate under TOS . 
i Ee 
Any disk has to have the sectors and tracks recorded onto it 
before it is useds eost systems have other information placed on 
the disk as well. The way TOS operates is by being written itself 
to each side of a disk. 
When the system is ‘booted’ up TOS is there snd is transferred 
into the controllers nenory. 
This process of preparing the disks for use in this way is called 
FORMATTING. 
The syntax is! 

FORMAT 8*drive name® TO “disk name’ 


CAUTIONS FORMAT = DESTROYS ALL OF THE DISK CONTENTS ! 


The only way to prevent a disk from being FORMATTED is to use the 
protection tabs on the disk . 


This is the only TOS instruction where the Drive naner and disk 
nane aust be specified. The names of the four drives are ArBrCrD. 
Where only one drive exists it must be drive A. 


The demonstration disk side A has all] the demonstration progrannes 
and the operating system TOS on the disk on side A. CAT 8, The 
directory commands will show that there are files there. Side 6 
is not FORMATTED: so will need doing straight away. 

Side B is accessed by placing the disk into the drive door with 
side B facing upwards. 4 


RESET 3 On the controller to reset TOS 

Remark! Red light of disk A flashes on for ao while then stops 
Renark? The sign that TOS is being read from the disks a1) ok 
Resark? Turn disk over to side B 

Enter $ CAT & ; 
Remark? Disk keeps spinnings but stops with error report 
Renark! Error report! Hardware fault on disk DEMO 

Reaark? This occurs because the disk is not FORMATTED 


The disk aust have a name to be used for the FORMAT Br let it de 
Test. Follow the instructions to see how it is done. 

Reaark? turn disk over to side A 

Remark? FORMAT = will clear 311 data from a disks be careful 
Enter 3 FORMAT #°A® TO "test® 

Renark! TOS responds! Format disk in drive A (Y/N) ? 

Enter 3% Y 

Reaark? Change disk and press ENTER 

Reaark? turn to side B 

Enter % ENTER 

Remark’ This sllows formatting with e one disk systen 

Renark! It takes about 30 secs to forest 

Remerk? It steps through 40 tracks and then writes TOS across. 


The systea is written to the disk and uses up 146k of space an the 
disk. There is anather 4k used by the directory for the disk. 
You can notice that the system is written to the disk last and 
takes place while the light is flickering at the very end. 


To format the disk B the principle is exectly the samer except 
the drive neae is disk B. If the disk nase was “°NEHDRIVE*, 
then the comasnd would sppear like this! 


FORMAT =°B* TO “NEWDRIVE® 
In this case there aust be a systea disk in drive A for the systea 
to works and there would be no delay for disk changer which is 


there to allow the change of disk needed to format s disk in a 
single drive systea,. 
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re sree pre 
LOAD = / SAVE x “transfer between disk and RAM (meaory) 
rr eee eee 
LOAD & and SAVE B sre similer to the standard LOAD and SAVE 
instructions of the SPECTRUM, except that a2 nane snust be 
specifiedr and TOS treats all characters ss upper case. LOAD m** 
will produce an error report, 


The LOAD °* of the SPECTRUM is useful when the nane of the 
progreane is not known. In TOS the CAT © comasnd displays the 
directory of the files on the disk» making is easy to find the 
progrseene needed. 

The sane options of LINE» CODEs SCREENS and DATA exist 


The syntax for BAVE ® and LOAD 2 is the followings 
SAVE = pathnane LOAD-OPTION Cn) 
LOAD = pathname LOAD-OPTION 


When the path in SAVE © refers to en existing file TOS proapts! 
<> already exists ; 
Supersede (Y/N) ? 
A “Y° will overwrite the file <> whilst °M° will ignore the 
comsand. If the Cn] option is used then TOS will carry out the 
command without proapting. 


The OPTIONS aret 


SAVE = pathname LINE nuaber ~save with auto run 

LOAD = / SAVE & pathname SCREENS -save a screen 

LOAD = / SAVE = pathnaene CODE startrlength -save machine code 

LOAD = / SAVE © pathname DATA array name () -save string array 
or numeric erray 

Try the following’ 

Renmark? Using the denonstration disk in drive A SIDE A 

Enter 3 CaT « 

Remark’ All the files in the directory displaved. 

Enter 3 LOAD =°HELP.BAS® 

Remark’ The optional typ is separated by a . (dot) 

Renmark’ To stop 8s prograsme use BREAK- Ccapshift space] 

Enter Press ENTER and then LIST 

Reaark? The programne listing sppears on the screen. 


Exsaple prograeee to generate es screen! 
Clinked to the exercise following) 


10 REM TOS.BAS 

20 PAPER 3 

30 FOR I=1 TO 704 

40 PRINT Gers 

50 NEXT I 

60 PAPER 6 

70 PRINT AT Sx1i38° TOS ° 

80 PRINT AT 1371238° * 

90 PRINT AT 1557%° OPERATING SYSTEM ° 
100 STOP 


LOAD = / SAVE & 
Try the following? 


USING LOAD = / SAVE 8 


Using side B of your desonstration disk? 


Enter % SAVE B*tos.bes* LINE 10 

RESET 3 Using the reset button on the interface. 

Enter 3 CaT « 

Remark! The prograene TO8.BAS should now be in the directory. 
Reaark? The SPECTRUM aemory is clear. 

Enter 3 LOAD =°T0S.BA8° 

Remark? The prograame autoasticaliy runs. 

Reaark? The prograame was saved using lower case, 

Enter % SAVE K°TOS.SCR® SCREENS 

Reaark! “The screen seaory image is saved es bytes in aenory. 
Remark? CAT & will confire the screen has been saved: 

RESET 3 Using the reset button on the interface. 

Enter % LOAD =*TOS.SCR* SCREENS 

Renark’ The screen aenorytaddress 14384evith 6912 bytes loaded. 
Enter 3 SAVE =°TOS.COD® CODE 1638476912 

Remark? Save option of CODE start address: length 

RESET 3 on interface 

Enter LOAD w°TOS.COD* CODE 1638456912 

Remark? Exactly equivalent to load with screent-now you know why 
Enter ¢ CAT « 

Reaark? New screen ! 

Enter $ SAVE =°TOS.SCR® SCREENS 

Reaark’ TOS prompts you. (answer no) 

Enter 3 SAVE =°TOS.SCR® SCREENS n 

Reaark? No prompting ! *TOS.SCR® is overwritten. 


The use of Arrays in BASIC is the asin way of cresting Data 
storage. TOS provides additional file handling capabilities in 
sequential and randoa access files. Deta can still be saved in 
arrays using TOS. 


The syntex for s string srray nased pt which is to be saved as 
the date file ‘nase. dat® is’ 


SAVE w*neme.dat® DATA pté() 
to load: LOAD B*naee.dsat* DATA p$() 


Were the array nuaeric the syntsx would only differ in the nase 
for the array which would have no ‘6 after it. 


Using the file type to indicate the type of dats in the files the 
right Load-option can sore easily be chosens avoiding the 
likelyhood of data type sisnmatch. E.g- a SCREENS type cannot be 
loaded using LOAD s°filensne*. 
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3.8 


MERGE & ~-perge one prograsse on another 


The syntax is MERGE = pathnane 


This serges 8 new progrsase and its variables: specified by the 
pathnase with the old programme in the SPECTRUM nenory. 


The new file aust contain » BASIC programme and overwrites any of 
the progrsase lines or varisbles in the old programme with line 
nuabers that conflict with the ones of the new progranne, It is 
not possible to serge bytes or arrays . 


RESET 3 On the interface 

Renark? Use side 8 of Deso disk 

Type ¢& 40 PRINT. ° #3 

Enter 3 SAVE z°TOS.OVL® 

Enter CAT «x 

Remerk? Programae ‘°TOS.BAS® and °TOS.OVL® are on disk 
Remark?! Going to overlay TOS.OVL onto TOS.BAS 
Enter 3 LOAD «°TOS.BAS* 

Enter 3% MERGE 2°TOS.OVL® 

Enter 3 Press ENTER 

Reaark? Line 40 is changed by the MERGE = 
Enter 3% RUN 


TEMPLATES -emasks for any nase / character 


A template is siailar to the ‘Joker’ in a pack of cards: because 
it can be enything. A template will sllow s selection over s 
nuaber of filess by for exaaple selecting ell those beginning with 
@ particular characters or all those with » BAS type extension. 


There are two ciaptaten characters or wildcards in TOS as follows! 
+ (plus) replaces 311 the names or type 
? (question aark) repleces s cheracter 


A pathnease with at least one of these characters is celled ~a 
TEMPLATE 
Selection of files covld be done like this? 


*+,4+° “nase and type asasked 

*+,Bas°® -any name with BAS type 

Bee “any file with no type 
°C77777277,%° -any @ letter file starting with C 
"cee -File starting with C and no type 


Templates sre very useful for checking directories using CAT * to 
find s particular type or group of files. They can be used with 
the following instructions! 

cat & LET =z 

ATTR = MOVE & ERASE # 


“Instructions needing a specific argument such ss GO TO ® cannot 


use TEMPLATES. Go to enywhere is meaningless! 
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3.11 


ATTR & ~protect / unprotect file 


The ATTR & instruction sets the file attribute to ‘protected’ or 

‘unprotected’ and to ‘visible’ or ‘invisible’ as required. 

The syntax is? 
ATTR * pathnsne 
ATTR = pathnane 
ATTR KZ pathnane 
ATTR = pathnane 


~to Protect a file 
-to Unprotect a file 
-to Hide a file 

-to Unveil s file 


<cwce 


Teaplates are allowed to lock or unlock ranges of files.This 
protection is useful to prevent inadvertent erasure or altering of - 
e file. 


Files that sre made invisible with this comeand will not be 
displayed when a CAT = is executed. ‘Visibility’ can be retrieved 
by using the ATTR & pathnane v command. 


Try the following! 


Reaark? use side B of the deao disk 

Enter 3 CaT = 

Remark? last col of directory is protect state 

Reaark? Programae *TOS.OVL® is on the disk. 

Enter ATTR =2°TOS.OVL°P 

Reaark? P does not appear in protect coluan straight away. 
Enter 2 Cat 2 

Remark’ Now the P appears showing the file is protected. 
Enter 3 ATTR m°+.4°U 

Remark? Unprotects all files 

Enter 3 CaT & 

Reaark? All files are now unprotected nothing in last coluan. 
Enter 3 ATTR u°e,4"p 

Renmark? All files are now protected on side B of Deno, disk. 
Enter 3 ATTR wet. e*d 

Enter 3 CAT « 

Remark’ Wo files displayed by the CAT = coassend 
Enter 3 ATTR B°*.4°v 

Enter ¢ CAT = 

Renark! All files visible once sore 


ERASE « -erase file 


When files are no longer needed the best thing to do is delete 
then the instruction for this in TOS is ERASE =. 
The syntax is? 

ERASE & pathnane Cn} 
Templates can be used. ERASE = will not delete a protected file. 
TOS prompts you with the following response before taking action 
unless the (nl parameter is givens then it will be carried ovt 
without TOS askings no proapt! 

Erase < > Y/N ? (<> represents the file naae) 

Y will execute the conmand 

N will stop the file from being erased 


16 


3613 


3.14 


LET « -change nsae 


This instruction to renase s file in TOS ist LET = 
The syntax is! 

LET 2 old pathnane TO new-pathnese 
TO is @ keywords and cannot be the characters TO separately. 
Protected files can be renaneds where the protection is at the 
file level with the software. If the directory hes been write 
protecteds renaming would still be possible. However if the disk 
hes been softusre write protected TOS will prevent renaming. 
Setting the hardware protection tab also prevents nane changes. 
TOS gives en error message explaining the protection level. 
Trying to rensme an open file or using teaplstes will generate 
error sessages from TOS. 


MOVE = “-copy source to destinstion 


Creating copies of disks sand prograanes is an essential part of 
using e disk systea. Teportant works and progrsaaes shovld be 
backed up. 


If you ere using @ single disk system» you will need to use the 
utility progreames which is on your demo disk in order to creste a 
copy of an entire disk, Details are in the appendix - Utility 
prograanes. 


A disk copy may be mede where there sre two drives by using the 
copy comaand and specifiying the target directory» into which the 
files ere to be copied. This is dealt with in section covering 
directories in CHAPTER 4 


The syntax ist 

KOvE B source-nane TO destinstion-nane 
Try the following! 
USING - MOVE = ERASE ® LET & 


Reaark? Using side B of the deao disk. 

RESET 3% on the interface 

Enter 3 CaT & 

Renmark? P in the lest coluan indicates file is protected 
Renark’ Can 8 protected file be rensned? 

Enter 3$ LET m°tos.ovl*® TO "rensaed® 

Reaark?! No obvious change - directory needs refreshing 
Enter % Cat « Q 

Remark’ The neae is now RENAMED with no type 

Renaerk? The file is still protected with the neae chenge 
Enter 3% MOVE z°rensmed® TO *tos.ovl® 

Enter 3 Cat sg 

Reeark’ Now the original copied from the rensped is back 
Renerk’ copying creates s duplicate of the file 

Enter $ ERASE =°renened® 
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Remark: Protected files cannot be erased 

Enter °$ ATTR K’renaned*y 

Remark? Uneprotect the file 

Enter ¢ ERASE E‘renaned® 

Enter 3 CaT «x 

Reaark! That did it 

Enter ¢ ATTR ucte.4+%p 

Enter 3 ERASE m*+,+° 

Reaarki TOS lists sll the protected files not erasable 
Enter 3 ATTR w*4,4%u 

Enter 3 ERASE x°+,4°n 

Remark’ TOS erases 81] files without prompt of Y/N 
Remark: The Deao disk side B - 911 prograanes erased 


Start -creating start up files. 
es SPS 
TOS esllows vou to create s start up file which is sutomatically 
loaded into your SPECTRUM and run every tise you reset it (power 
up or RESET button on the interface). 

To use this feature you must SAVE = your start up progrsane with 
the auto run facility and call it “START*.Now every tise 8 reset 
is executed TOS will look fors 2s progrsame nssed “*Start® in drive 
A if it exists then the SPECTRUM will run it. 


Remark’ To be able save the prograame displace the disk 
protection tab. : 

Remark’ Using side A of your diskette 

Enter 3 10 LOAD =°HELP.BAS® 

Enter 3 SAVE m°START® LINE 10 

Remark: Creating 8 programme named *START* 

Enter 3 CaT = 

Reset ’ Using reset button on interface, 

Remark? Help-ebas runs automatically. 


If ‘vou have 8 prograane nsaed “START® and you want to teaporarly 
avoid its execution use BREAK while pressing the reset button on 
the interface .If you don't wish to use it at all siaply. erase it. 


Try the following °START® progranaet 
10 CAT « 


20 INPUT °Name of file to LOAD 7? °tat 
30 LOAD sas 


CHAPTER 4 


TREE STRUCTURE 


A Tree structure has a stem linked directly to the root. ‘There 
are branches which sre directly linked to the roots but there sre 
branches which grow ovt of other branches»: and so on. 


The path froa eo lesf to the roots may involve passing through 
several branches, on the way to the root. 


The path may be very complex if the branch that the leaf is 
connected to is itself connected to other branches: but may also 
be very siaple if there is 9 direct connection to the root via the 
stea. 


The directory structure of TOS is analogous to the tree structure! 


There is 8 root directory which contains other directories. 

A directory aay contain files and /or directories. 

Directories can be nested one within snother,. 

From any directory to a file (or directory) there is 8 specific 
route called the PATHNAME 

A PATHNAME is 8 specified route of moves from s source directory 
through the tree structure to a file together with the filenane. 
- The PATHNAME can be the filenane itself» when the file is within 
the source directory and no move is needed to reach it. ; 


Notet Source directory does not mean root directory: but any 
directory which is the source of the paths in the PATHNAME. 


The edvantage of being able to nase directories in this way aeans 
that the possiblity exists for grouping information or progrsaees 
into convenient divisions. When many files exist on 3 disk it is 
only necessary to CAT & thst directory containing the files 
thus svoiding the need to have several screens of files displayed. 


Grouping file types under one directoryrs will sake accessing thes 
easier. For exaaple if the BASIC programmes are in one directory 
end the mechine language progrssees are in anothers then accessing 
end using the progrsanes is easier and leaves less chance of 
errors trying to LOAD & @ programee with the wrong Load-Option. 
Including the extension typerwhether .BAS to represent BASIC or 
«COD to represent CODE or whichever extension is convenient to 
identify the file types is useful: especially when large nuabers 
of files sre on the disk. 
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ADDRESS. REC COLOURS 


a Sl ete tn SR AE TSE 


Introducing TOS with DIRECTORIES 

re er er) 
It is iaportant to identify the difference between the directory 
and the file. The directory contains the reference to where the 
file is rather like an index to 8s book does. TOS is organised in 
a hierarchic structure seaning that it is possible to have files 
and /or directories inside directories. The directories appearing 
just like any other files inside a directorys but they always have 
a DIR type extension to the nane. 


There are two special files with the extension SCP» these are 
serial comaunication portse end srei CH_A.SCP and CH_B.SCP, 
these may also appear in the directory listing and are dealt with 
in the last chapter. 


The structure of your system with the denonstration disk iss 
shown below: 


*ROOT® [__] -rme 
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ADDRESS .BAS 

BACKUP LOsYS LINEAR] 
HI-LO TYPE RSTRANS RANDOM 

Figure «2-6 

TOS provides various ways of moving sround the directory structure 


es well as sethods of creatingr erasings protectings caopyings and 
renaming a directory. 


4.3 THE PATHNAME | 


The TOS use of PATHNAME allows access to any file on whichever 
disks or directory that it is in. 

The directory which is the one that TOS is currently ats is terned 
the default or current directory. When a8 command like CAT x is 
performed it uses as its argument the current directory name» and 
produces the listing of that directory. 


The tree structure that TOS uses should be considered 88 an 
inverted trees with the root st the tops and the branches coming 
down. This is so that aoving ‘up’ the trees involves moving back 
upuards to the root. Moving down involves soving through naned 
directories towards the lower branches. Moving downwards the 
brenchesr provide alternative routes. This is why TOS will insist 
on having directory nsaes specified on the way downs but will 
accept '4'(an up arrow) as an instruction to move upr because on 
the way up there is only one way to go. 


4.4 Using TOS PATHNAMES 


TOS can use patinanes in the majority of the instructions such as 
LOAD =sSAVE SeMERGE Be CAT Be ERASE Ke MOVE Be ATTR BeOIM & PLET & 
These instructions function in auch the sane way as they would 
veing 2s filenames but have the asdditional options aveilable 
through the added ability to work through the pathnsnaer and so 
operate across the boundary of the directory, 


Vnere are several points to note sbout pathnases as follows} 

~The pathneee is 8 compound naner defining a path from the current 
directory to a file (or a directory). 

-Directory naees on the path aust be seperated by es colon (3%). 

-The root directory aay be represented by 9 colon (!). 

“Any paethnese can be defined from the root directory by starting 
the pathnase with » colon. 

“Any pathnese not starting with s colon will be from the current 
directory, 

-The pathname is treated as s BASIC string end is within quotation 
merkiss and can be represented by string varisbles. : 

Referring to figure 2 of the directory structure in the deao disks 
the pathname can be studied in relation to the following exseples’ 


RIE ee woe eee cues PATHNAME_ 
Calender bas "3DEMO3 FUNS CALENDAR. BAS* 
Hi-lo.bes * DEMOS FUNSGAMESSHI-LO.BAS* 
Roots.bas *“3DENO! MATHS! ROOTS.BAS® 


The pethnase consists cf @ ‘path’ through the directories together 
With @ teruet ‘filenane'’. TOS helps you to know where you are by 
printing cut the ‘path’ to the current directory st the head of 
the directory listing. How ever far down es directory tree you go 
this inforastion is always in the directory» together with the 
level of nesting of GO SUB = level of the directory. 
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PE NTE ETS 


OIM s 

ee ee ee 
There are times that it is necessary to creste files that are not 
for storing programmes or screenés but some other kind of 
information. The DIM & instruction is provided by TOS for this 
purpose. 


The syntax isi 
DIM = pathnane 


DIN = creates a file or a directory. The use of the path seans 
that files can be created outside the current directory. 


To create a directory the DIR extension aust be included» letting 
TOS know it is ea directorys otherwise s file would be crested, 


Using OIM = it is possible to create up to 16 directories on each 
side of the disks that includes the directory corresponding to the 
disk itself. This seans 15 new ones can be createds the structure 
is entirely up to the user. Attempting to create sore than 15 
will generate the error report! cannot create sore directories, 
Directories may be nested withing each other of directly under the 
disk's pain directory, at the sane level. 


OIM * cannot be used to create sn SCP (Serial Conmaunication Part). 
Trying to do so would produce an error report of wrong type. 

DIM x cannot be used to creste a file thst already exists. 

If a file “*newfile® exists then DIM B*newfile® would generate the 
error’! NEWFILE already exists. 

A sisiler conflict would occur trying to DIM B*newdir,dir’s that 
already existed. 

Creating a file of the sane nase as 8 directory is not allowed. 
Atteapting to open a file ‘newdir’s without any type extension 
would still produce the error! NEWDIR already exists. 


The pathneae can be a string variablerand the DIN & instruction 
used as 8 programme statesents as in the following exanplet 
Two directories are opened using s direct command as follows! 


DIM Z°NENDIR.DIR* {DIM B°NENDIRIDIR1.DIR® 


10 REM Create files 

20 LET a$=°° 

30 for i=1 to 8 

40 LET at=aS+STRS i 

SO DIM w*neudiridiris *+at 
" 60 NEXT i 


Remark? Use side B of disk» eae = the above programee . 

Enter 3 SAVE E°CREATE* 

Enter 3! RUN 

Enter ¢ CAT B*newdiridiri® 

Resark; In directory °dirt*aretiel221239123949.0000000912385678 
Remark? All the files are crested with size zera 
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GOTO zs ¢s/ 3s LIST ® 
ge PPh ces 
The default directory can be changed to another directory by using 
the GO TO = instruction. 


The syntax is? 
GO TO ® pathnase 


A special instruction exists to nove up through the directory 
structure which is! 

co To x*4° -move up one directory level 

GO TO =°49° - Two levels 


Any nuaber of levels can be aoved up in this ways but there is a 
short fore of returning to the top (the root) which uses a colon 
and is as follows! 

GO TO x°3° -goes to the root directory 


The plsce you sre in TOS is slwevs stated at the top of the 
directory. TOS allows thet information to be displayed by itself 
using the LIST = commands along with your directory location. 


GO TO = end LIST = aay be vsed ss 8 prograene statenents. 
The pathname may be a string variable. 


Remark? Using side A of your deao disk. 

Enter 3 CAT me3* 

Remark’ The physical resources of your system sre displeved 
starting with the nane of the disk in drive A followed 
by the two SCP's. 

Remark’ Another way to displey the root is » 

Enter 3 GO TO z°3° 

Enter 3 CAT & ‘ 

Remark’ Suppose you Jjust wanted to know the size of the file 
“HI-LO.BAS*® 

Enter 3 CAT e°DEMOSFUNS GAMES SHI-LO.BAS* 

Enter 3 CaT = 

Rensrk! Your current directory is still the sane. 

Reaark! If you wanted to sake “GAMES® current directory 

Enter 3 GO TO m°DEMOL FUN? GAMES? 

Renmark’ To know inforastion about SHI-LO" 

Enter 3 CAT 2°HI-LO.BAS® 


TOS allows you to change your current directory to another drive 
without knowing the disk nane. The syntax is! 


GO TO S°ORIVE NAME’S 


Where the “ORIVE NAMES can be As Bre Ce or D. Specifiyng 2 pathnane 
is not, allowed when using this facility. Refer to Section 4.9 . 


— 
GO SUB x / DRAW & 

ee re 
It is very useful to go to a directory perform whatever 
instructions are needed and return back to the source directory, 


TOS allows this using the GOSUB © instruction followed by the 
DRAW & instruction. The process is very sisilar to a subroutine 
call in BASIC. TOS uses 8 directory stacks which holds information 
on the level of nesting of these calis. TOS allows 8 levels of 
nesting of subroutine calls to directories in this way. 


The syntax is? 

GO SUB = Cpathnane) 
The pathname between brackets means that it is optional. 
GO SUB = is used in conjunction with DRAW 2 swhich causes =e jump 
back to the original directory. The level of GO SUB = nesting is 
displaved at the head of the directory listing produced by CAT x, 
It does not matter which directory is current it will always be 
level O» unless s GO SUB = has been executed. The level refers to 
the level of nesting on the stack. Every time s ORAW 8 is 
executed, the level drops by 1. An error will result fros trying 
to DRAW * from level 0% cannot return from level 0. 
The advantage of using GO SUB xX instead of the straight GO TO x 
instruction is that TOS sutomatically keeps track of your route 
and will ORAW = you to where you started» and the way back 
requires no arguments just DRAW EZ. GO TO = would require the path 
specified for the rovte back. You can also use °¢° to move up 
levels of directories. 


LIST ®& displays the contents of the directory stack shence for all 
the levels the following information? 
PATHNAME? LEVEL» and DRIVE () 


Remark’ Using side A of your deao diskette 

Remark’ You want to save your current directory in the stack for 
later use but you want to remain in that directory. 

Enter $ GO TO =°?tDEMO%FUN® or GO TO X"DEMO{FUNS if you sre 
still st the ‘ROOT’ 

Remark: Makes °FUN® your current directory 

Enter LIST « 

Enter ° GO SUB = 

Remark? No pathnsee. Current directory saved on stack. 

Enter 3 LIST 2 

Remark?’ The current directory is the ssse but the directory 
level has been increaented. 


Enter 3 GO TO «°{DEMOSMATHS® 
Enter 3 CAT ® 

Enter 3’ DRAW « 

Enter 3 LIST s 


Remark’ You got back to your first directory. 
Like with the GO TO = coasand this instruction also permits the 


usage of the d parameter (GO SUB **drivenane'd) which will enable 
you to change drives without specifying the disk nase. 
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DEMO DISK 


PE a TP SCN TEES 


The Demo disk contains programmes on side A that should be used 
for the following study of the directory structure. 


“ The pathnase making use of nested directories will. be used» 


together with the preceeding set of instructions. 


Remerks on how cospound pathnanes differ from paethnanes with no 
‘path' in relation to the instructions introduced in chapter 3 
will be dealt with at the end of the next section. 


Try the following’ 

Remark! Using side A of the Deao disk 
Enter ! GO TO m*3° 

Reaark’ go to the root directory 
Enter 3 CAT « 


Reaark? DENO.OIR 
Renark’ CH_A.SCP 
Reaark! CH_8.SCP 


Enter 3 GO SUB =°DENO* 

Remark’ Going down the trees but can easily return. 
Enter % LIST = 

Remark! Tells us where we are 

Enter CaT = 

Renmark! See what is available? 

Renark? Help.bsas only programmes rest sre directories : 
Enter 3 LOAD =°tDEMOSHELP.BAS® or simply LOAD s*HELP.BAS’ 
Renmark?’ using » compound pathnaee in LOAD = 

Reaark? Running helper you find it is «9 TOS summery 
Renmark! A progrease can be stopped using BREAK 

Enter 3 CAT & 

Renark?’ using LOAD = did not change the LEVEL froe 1 
Enter % GOSUB x°FUN® : 
Enter 3 CAT x 

Reaark’ level 2° & pathname on top of directory 

Reaark’ What ebout a gene! 

Enter 3! GOSUB =°GAMES® 

Enter 3 CAT « 

Reaerk! Play dice! 

Enter 3 LOAD xz°DICE.BAS*® 

Remark! When you heve hed enough BREAK {(CAPSHIFT SPACED 
Reasrk! How to go and get help again 2 

Enter 3! LOAD m°SDEMOTHELP.BAS® 

Reaark! After finishing see where we are 


‘Enter % CAT m or LIST & 


Remark! We did not aove from the current directory 
Enter DRANK « followed by LIST 8 

Renark! each DRAW & moves down 1 level 

Enter 3! Using GO TO =°f 4° or $ would get back to root 
Renark! use GO TO ® instead of GO SUB = doing it again 


tr St 
ATTR = LET = MOVE & ERASE = LOAD = SAVE & 
ee 
The way these comaands operate with files» is similar to the way 
they operate using directories»: however there are differences» 
based on the fact that a directory can contain a file. This neans 
that operating on a directory will sffect the file. Sone 
instructions cannot be used in the same way with directories. 


ATTR «MS can be used to protect sunprotect seveil or unveil 
directories in a similar way that it can be used with files. as 
an exaaple’ 

ATTR w*Newdiridirit+.+* u 


Will unprotect all the files in °diri® 


LET xe Directories can be renased just like filess but only 
when there are not any files currently open. As an exanples 


LET e°tDiski® TO *thork® 
Will rename directory ‘Diski® to “Work*. 


MOVE =: The copying function cannot be used to copy a directory. 
However the files from within can be copied freely from one 
directory to another. A utility beckup progreame exists which 
will perform the function of a disk copy when needed. This 
programme is on the disk that you received with TOS» and its 
functioning is explained in the sppendix C. 

A file can be copied from one directory to snother like this! 


HOVE B°create® TO ‘newdiricreate* 


MOVE x can also be used with SCP'ss copying to thea and from thea 
just like other files. You can even copy from one SCP to the 
others which could be useful for echoing the input from CHA to 
CH_E» could be used in testing 8 device equipped with an R8232C 
interfacer like a video terminal or other coaputer. 

MOVE m°SCH_A® TO *3CH_B* 
A File can be ‘sent’ to an SCP using MOVE = as follows? 

MOVE &°Tos.bas* TO “$ch_b* 


CAT «i Can be used simply by adding the full pathnane as 
follows: CAT B°newdiritdiri® to list all the files on "diri® 


ERASE x3 can be used in auch the sane way as with files» except 
you cannot erase the names defined in the roots like the actual 
name ‘of the disk and the SCP's. Erasing a directory will erase 
all the files within ite but if a directory contains another 
directory it cannot be erased. All files have to be closed before 
a directory can be erased» or indeed even s file that is open 
cannot be erased .If there are files within a directory that are 
write protecteds then the directory cannot be erased until they 
have been unprotected. You can ERASE © unprotected files inside 
protected directories. 


There is an option using ERASE = that allows files to be erased 
without offering the Y/N proapt that is normal. This is using the 
n options which works like this! 

ERASE x°+.+°n -no proapting 

ERASE u°+,+° -will give Y/N choice for each file 


LOAD 8/SAVE 3 can be used in exactly the saee way as with 2a 
single file except including the full pathnane. This way you are 
able to save or load progrsmnpes from any of the directories in the 
system» from the current directory. 


SAVE R*3NENDIRSDIRISCREATE® -saves the prograsme in diri 
LOAD =°{NENDIRIDIRIICREATE® -to load it 


Try the following! . 

Reaark’ Using disk 8. With the program °CREATE® we generated 8 
files with numeric nanes in section 4.5 

Enter 3: ERASE m*NENDIR® 

Remark? Can not ERASE = @ directory that contains directories, 

Enter % GO TO x*NEWDIR' 

Enter CAT e*DIR1I° 

Remark’ Create another directory and copy all files into it 

Enter 3 OIM =°DIRZ.DIR® 

Enter 3! MOVE K°DIRI$+.%° TO *DIR2Z° 

Enter 3 CAT w*OIR2° 

Remark?’ All the files in diri copied to dir2 

Remark? protect/ unprotect diri and files then erase theal 

Enter % ATTR B°DIR1I‘P 

Enter 3 ATTR B°DIR1I$4+.4°P 

Enter $ CAT x3 CAT R°OIRI® 

Enter 3 ERASE xm°DIRi°* 

Enter 3! ATTR w°DIRICU 

Renmark’ The directory is unprotected, but files are protected 

Enter ERASE B°DIRI3+.+° 

Remark? Files need to be unprotected for erasure 

Enter 3 ATTR KE°OIR1I3+.+°U 

Enter $ ERASE «°OIR1312345677° 

Enter $ ERASE R°DIRIL773+° 

Remark’! Study selective erasure using teaplates 

Enter 3 ERASE K"DIR1I2+.+° 

Remark! Renasing a file/dir 

Enter 3 LET m°DIRZ312° TO “DIRZ%RENAMED® 

Enter 3 CAT «°DIR2° 

Reaark’ Rename eo directory 

Enter 3 LET =*DIR2Z* TO *OIRNER® 

Enter 3% CAT x*DIRNEW® 

Enter 3 ERASE x°DIRNEN® 

Enter 3 CAT @ 

Remark?! Erasing a directory will erase the files within it 

Enter 3 ERASE =°OIRi® 

Enter 3 GO TO x°¢* -Meke test your current directory 

Enter 2 ERASE R°NEWDIR®? CAT = 

Enter 2 ERASE «*CREATE® 

Remark? Side 6 of deao disk now eapty . Use side B for CHAPTER 5 
examples. 
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USING TWO OR MORE DRIVES 
SD 
As you know the ROOT represents the physical resources of your 
systea.You can connect up to 4 drives (A to D) as well as the two 
communications ports (CH_A and CH_B)-see section 2.3 « Knowing 
the names of your disks ( to do that you CAT & the ROOT’ )» you can 
access other drives just by specifying a pathnane starting at the 
ROOT or at your current directory. 

To access the other drives treat thea as if they were directories 
placed inaediately under the ROOT . So if you wished to aove rsay» 
to the disk in drive B you could type! 


GO SUB = or GO TO =°tName of drive B disk* 
Try the following exanmplet 


Remark? For users with sore than one drive 

Remark? Using side A of deao disk and a blsnk disk in drive 8B 

Enter $ FORMAT «°B* TO °NEW® 

Enter 3 Y 

Remark? Formatting drive 8 

Enter ! CAT we"? 

Remark’ You now have two disks 

Enter ° DIM B°SNENSMATHS.DIR® 

Enter $ MOVE E°MATHS3+.¢° TO *SNEWSMATHS® 

Enter °’ CAT =*SNENSMATHS® 

Enter ¢ CO SUB x 

Remark? Use of GO SUB & without s pathnsae,. 

Enter % GO TO =*tNEWSMATHS® 

Enter 3 CAT & 

Remark? Your current directory is MATHS in drive B 

Enter 3 ORAW = 

Enter 3 CAT & 

Remark’ Return to previous directory 

Enter 38 LOAD B°S NERS MATHSSROOTS.BAS® 

Remark? Now try changing vour current directory to MATHS in 
disk B snd LOAD w&°LINEAR.BAS* 


Try the following to understand the way of changing drives without 
knowing the nases of the disks. 


Enter 3 GO TO =*°?DEMO* 

Remark? Your directory is now drive A 

Enter 2 GO TO R°B*d 

Enter 3 CAT x 

Reaark? Your current directory is now °NEW® in drive 8B. 
Remark? Try to go back to drive A using GO SUB K"A‘d 


CHAPTER 5 


— mal 
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FILES 


A file may be thought of as a collection of pieces of information 
bound to the ssme name. Until now the concept of a file as a 
whole unit has been used. A BASIC programme is an example of 2 
such a file. Using the SPECTRUM in the traditional way, data for 
exanple would be contained in an arravr to access any data the 
whole file would be losded and accessed as a whole. 


A feature of TOS is that it permits the resding of a part of a 
file without the need to read the whole file. This feature is 
especially useful in preparing large data files where individval 
records from the file are to be sccesseds as needed for exseapler 
in date beser stock control spplications: and other business 
applications. This allows the creation of files of any size no . 
longer limiting your applications to the size of the SPECTRUM 
menory. 


ere SS 


CHANNELS 


TOS accesses (reads or writes) files through channels. A channel 
is o# nuaber associated with a file that you use to refer to it in 
the instructions PRINT = (which writes) and INPUT & (which reads), 
A channel also acts as 8 data buffer (through which data fiows) 
with some senory containing information on the filer such as its 
neaes sizer etc. } 

10S provides you with 16 channels. To access a file» choose sa free 
channel (one that is not being used to access another file) and 
associste it with the file. 

To open a file use the OPEN @= instruction. The PRINT = and INPUT 
Z instructions refer to output and input to a file through the 
chennel nveaber - which beconses exclusive to this file until you 
close it with the CLOSE @= instruction. 

Closing # channel frees it» and disessociates it from the files 
preventing further access to the file. 


OPEN ¢z 


The OPEN @2 instruction opens a filer that is, prepares it to be 
accessed (read or written). Essentially» this operation consists 
of associating s channel with » file and establishing the access 
mode. In all subsequent access operations the file is referred to 
by the nupaber of the channel you associated with it. 

You cannot eccess a file that is not open. Note howevers that we 
ere referring to read and write operations using the INPUT * and 
PRINT & instructions. 

You cen sccess a closed file as a whole with instructions like 
SAVE Bp LOAD & end MOVE Be but INPUT & and PRINT & are the only 
instructions that allow access to e specific part of a file. 
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The syntax of the OPEN @m instruction is? 
OPEN @= channel’ pathnanes node! Crec-length] 


The ‘¢* is printed by the SPECTRUM as part of the OPEN keyword.” 
The OPEN paraaeters have the following seaning! 


CHANNEL - Nuaber of the channel you want to associate with the 
file. This channel aust not be associated with another 
files and aust be in the range of 1 to 16. It can be a 
nuaeric expression. 


PATHNAME - Pathname designating the file. Can also designate an 
SCP.e but not a directory. Can be a string expression. 

MODE - Letter (upper or lower case) defining the access sode. 
There are four possibilities! 


Input only (You can only read the file) 

Output only (You can anly write in the file) 

Randoe access (You can only read or write the file) 
Append (You can anly write in the file. New 
information is appended to the previous one) 


>2oOn 
teeto 


‘REC~LENGTH 


This is an optional parameter if the aode is Ir 0 
or A and defines the nuaber of bytes (characters) 
of each record of the file. Must be 8 number in the 
range 1 to 256. Can be a numeric expression. If 
this parameter is omitted, the last semicolon aust 
not be present. 
Exseples! 

100 INPUT ° File name ? °3 f$ 

110 INPUT ° Channel number ?°3 n 

120 DIM =ft$ 

130 OPEN @zunifeti 

140 REM the file is now open and ready to be read 


2000 DIM x*Horkfile® 

2020 OPEN @8153 SWorkfile®srsi150 

2050 REM the file WORKFILE is now ready to be read 
or written to with a record length of 150 


The sode paraseter defines the access node (inputs ovtputs randos 
or append). The last parameter defines the record length. If 
omitteds we say that the file is open as 23 stream filet if 
presents we say that the file is open ss a record file. If you 
specify the rt aode you cannot omit this parsneter. 

This describes what the file structure is expected to be. If the 
file is apen as a streams files you can read or write a variable 
nueber of characters up to 256. If you open the file as a record 
files you can only read or write a fixed number of characters - 
the number’ you specified in the record-length parameter of the 
OPEN @m= instruction. 


Stream files are better suited to deal with information that has 
no special structure. Record files have an underlying record 
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structure and are particularly useful when dealing with data 
basesr where a record holds information of a fixed length. 

Stream files can only be read or written sequentially. When you 
perform consecutive INPUT & instructions on a stream filer you 
read the characters one sfter the other. 


Record files can be resd or written in 2 randoms eanner. You 
specify - using the ‘AT® statement - the number of the record you 
want to read with the PRINT & and INPUT & instructions. 
A file is accessed using eo file pointers understanding the concept 
is isaportant. In stream files the basic information unit is the 
character. In record files the basic informastion unit is the 
record (which can have up to 256 charaters). If you want to access 
a particular character in se certain records you aust read the 
entire record, Whichever the basic information unit is» an open 
file aelways hes a pointer pointing to it. In stream files this 
file pointer points to the character which will be read or written 
next. In record files: the file pointer points to the number of 
the record that will be read or written next. Record files can 
also be accessed sequentially» record after record. 


When the OPEN @= instruction is executed: the file pointer is 
initialised to different valves» sccording to the mode paraneter. 
Lf the file is open in input or output (stress or record files) or 
randos (record files)s the file pointer is initialised to 1s even 
if the file is empty. 


If the file is open in the sppend moder the file pointer is 
initialised with the file size plus 1 (stream files) or with the 
number of records contained in the file plus 1 (record files): 
corresponding to the nuaber of the character or record that is 
going to be written next. 


If you open a file in ovtput only moder all its previous contents 
will be destroyed. Using the append aode the data is attached to 
the end of the file without overwriting it. 

A record file will be overwritten by specifying a record nveber 
lower than the last one on the file. The changes made to s file 
become effective when you close it with the CLOSE #@@ instruction. 


You can also open and reed or write SCP'ss but the concepts just 
described vary. These are described in the next chapter devoted 
to SCP's. 


The following you cannot do with the OPEN @@ instruction! 

“Specify # channel already in use. 

“Specify e# channel ovtside the range 1 to 16. Or a record 
outside the range 1 to 256. 

-Specify a directory as the erguaent. 

~Specify a pathnane using 8 teaplate. 

“Specify se random sccess file without s record length. 

“Specify the opening of a file in write soder that is using» 
outputs random or append eodes» to a file or disk which is write 
protected. 
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3.4 


pr es i i 
LIST u¢ 

_—_— 
Tf a file or SCP is open the CAT & instruction displays an ‘0° 
under the °S* field. To know in which channel(s) the file is opens 
its moder type (stream or record)» use the LIST s@ instructions 
which displays inforastion on open files» and whose syntax is! 


LIST «@ Cchannel nuaber) 


The channel number is optional. If vou specify its TOS will only 
display information on that channel. If you omit ite TOS will 
display information on all apen channels. 


Try entering’ OIM =°TOS.SCR® 
OPEN #233 *tos.scr'si 


This instruction. opens the file °TOS.SCR* in channel 3 in the 
streze input aode. 
Now enter! 

LIST x@ 


The fist line listed is the pathnase of the files starting at the 
toot. Next comes a header and the corresponding information, Last 
line tells you how sany free channels you have left. The 
information on the open file includes? 


Ch - Channel number 1 to 16 

T - Channel type? slow (s) or fast (f) 

M - Modet Ir Or Re or A (one of the four modes in which 
you can open a file) 

Typ - File type! stream (STR) or record (REC) 

Rin - Record length (the number you specified in the 
OPEN @m instruction. If the file type is streaas 
the value shown is 1) 

Pointer - File pointer (this is the nuaber of the 
character or record that is going to be read or 
written nexts if the file is open ss a streas or 
record file respectively. The first character or 
record is nusber 1) 

Size - The size of @ file in bytes. In input onlyr this 

valve is fixed. In all other modes this value aay 
grow according to what you write in the file, 


Now enter? DIM =°TOS.BAS* {SAVE x°SCREEN.SCR® SCREENS 
OPEN @873°tos.bas"3r320 
OPEN @2163°screen.scr'ia 


followed by? 
LIST u@ 


This lists inforaation on 311 open channels. 


Please note: 


1) - Channel 3 is fast (T field) and 7 and 16 sre slow. 
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2) - File ‘*TOS.BAS* is open se a record file with record 
length (Rin) of 20 bytes (characters) and the file pointer 
is initielised to i. 

3) - File “°SCREEN.SCR° is open as 2 stream in append mode» 
which is why the file pointer is initialised to 6918 (one 
plus the sizes that iss the number of the character that 
will be written next). : 


Finallys 3 channels open leave 13 channels free. 
If there is no channel opens the LIST £¢ will print: 


146 channels free 
No channels open 


If you specify the number of a channel that is not opens TOS 
will generate the error sessage? 
Channel not open 


If you specify sa channel nuaber outside the 1 to 16 ranger 
you will get the error sessage! 
Tllegsl channel nvaber 


The LIST w@ will still work if the channel is open to an SCPr 
with s few exceptions (see chapter on SCP‘'s). 


RANDOM ACCESS end SEQUENTIAL files 
TS | 
This section describes the use of random and sequential access 
files. : 


Files can be used to store and retrieve inforastion other than 
BASIC or aachine code progreas. For exsapler they can be used to 
keep a record of your bank accounts your sppointaents or just a 
sequence of results from s calculation. 


The new coasands that allow you to use files from within a BASIC 
prograe work just Like PRINT and INPUT but act on files instead of 
the screen or the keyboard. 


To explain the use of these comsands two saall prograss will be 
used. The first deaonstrates the use of auAeRTeEs files: and the 
second of randoe or direct access files. 


Suppose you want to check if s nuaber aatches any of 8 sequence 
you have previously created and stored in a data file naned 
*TABLE.DAT®. 


First you have to create this file. The program to do it could be 
something like this? 


100 DIM x" TABLE.DAT® 
110 OPEN @z13°TABLE.DAT°SO 


He have crested the file and then opened it for output (0 
svebolizes output) through channel. 1, 


120 REM Table input routine 

130 INPUT *How many do you wish?°ta 
140 FOR n=1 TO @ 

150 INPUT "Enter Number’s ast 

160 PRINT "013 a8+4CHRS13 

170 NEXT n 

180 CLOSE @mi -< 


The main body of the program ends here closing the file.In line 
160 we do not print the number, but its string representation and 
use a carriage return (ASCII code 13) after the nuaber as a 
SEPARATOR. In @ sequential file such as thise the charaters are 
printed ane after another and items aust be separated: otherwise 
vou will not be able to read thee back separately. 


Several types of separators are recognised by the extended BASIC. 
You can use commasr tabs (CHR$6) or quotes. Quotes aust be used in 
pairs and everything between therm will be considered a string. 
This way you can save a string that has 2 separator code in it. If 
you want to save a string that includes quotes, then use two 
quotes like this! °*Hello**. 


After running this program there will be a file in your disk with 
all the nuabers you have entered. 

Use the following program to see how to check whether a nuaber 
belongs to this tsble or not? 


200 LET TRAP=23729%LET SYSERR=23728 

300 OPEN @m1is*TABLE.DAT*° #34 

310 POKE TRAP?255 

320 PRINT °O ends progrsa® 

330 INPUT *Number to check*in 

340 IF n®0 THEN GOTO 440 

350 INPUT x¢139$ 

360 IF PEEK SYSERR <>O THEN GOTO 410 

370 IF VAL (p$) <>n THEN GOTO 350 

380 PRINT °Nueber “°tnt* belongs to the table‘ 

390 RESTORE =¢1 

400 GOTO 330 

410 PRINT ‘°Nuaber ‘ini® does not belong to the 
table’ 

420 GOTO 390 

430 REM prograa end 

440 CLOSE ¢n1 

450 POKE TRAP?O 

460 PRINT *End of progranm® 


Line 200 defines variables used for error trapping-see appendix E 
Line 310 enables the error trapping routine. The loop in line 330 
checks if the number presently entered figures in our list by 
checking it against all the numbers in the file. 

If vou have already run the previous prograsme then enter run 200. 
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In line 350 a value is INPUT = from the file. This value is in the 
form of a string (p$) and is converted to a number in line 370 
using VAL. All information transmitted to or from a file must be 
in string format. 

The RESTORE in line 390 resets the file pointer so that every 
search starts at the beginning of the file. 


The eost isportant points concerning files and sequential 
access aodes srei 


- You can only use strings when reading or writing to a file. 

- These strings have a mnaxiaua length of 256 bytes. 

You cannot use string arrays with sore than one dimension for 

input. 

~ There must be 2 separator between strings in a file or you 

will not be able to read them back separately. 

- There aust be only one string expression in each FRINT «& 
statement. If you want to print several items join them by a 
plus signt “+*, 

6- In a sequential file you can only read or write items one 

after the other. 

7 ~ If you open an already existing file for ovtput its previous 

contents will be lost. 
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Another important point about files is record access. 


You can write to s file as if it were an endless taper separating 
the items for lester readings or you can define a fixed record 
length and every time you access the file the information transfer 
will be made in chunks of fixed lengthr disregarding the separator 
characters. For exaaple enter} 


DIM ="NAMES® (As @ direct command) 
100 OPEN #m1 °NAMES* 303930 

110 FOR n=1 TO 20 

120 INPUT "Nane* tins 

130 PRINT x@1ins 

140 NEXT n 

150 CLOSE ¢a 


This program will prompt for and write 20 names to a file called 
NAMES» each using 30 bytes. If n$ is longer than 30 bytes» only 
the first 30 will be written» if shorter» the renaining bytes will 
be filled with blanks. 


The names may be read back using this progran! 


200 OPEN @13°NAMES°#1730 | 
210 FOR n=i to 20 

220 INPUT 2613 a8 

230 PRINT af 

240 NEXT 1 

250 CLOSE ¢= 


This program works without using separators, but vou must know in 
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advance the tecord length you are going to use. You covld renove 
the carrisge return from line 160 in the program that generstes 
the *TAELE.DAT® file (see above) if you introduced a fixed record 
length in line 110. 


You must read the file using the same record length you used when 
you wrote its otherwise you will read back different strings fros 
those you wrote. 


This can be useful to study the contents of a file. For exseple! 


100 INPUT °Naae of file to read*int ‘ 
110 LET x#1 

120 OPEN @uiins3I31 

130 INPUT 201308 

140 PRINT xeass*® “SCODE st 

150 LET xexel 

160 GOTO 130 


will read a file and display each character and its coder until 
the end of file is reached and the prograe stops (try it with 
NAMES ). 


The mext example is on direct access files. With this type of 
access you can read or write to any place in the file but you aust 
use fixed length records. This sode is useful to define records 
such as those in an address book where each entry has a predefined 
size. 


The demonstration prograame reads records without resetting the 
file pointer every tise a search is asder and writes anywhere in 
the file withovt upsetting other records. 


This programs uses only one of the sixteen channels and the 
string slicing function to separate fields. Alternatively you 
could use several channels and allocate one to each of the fields, 
thus avoiding the need for the string slicing function. 
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Please refer to the program *ADDRESS* on your demo disk. 


90 LET TRAP=23729 

95 POKE TRAP:255 

100 OIM wB°address.dat*® 

110 POKE TRAP+0 

115 OPEN @m13 ‘address.dat®ir3100 

120 INPUT *1=Reads2=Write and 3*End* ths 
130 IF h$=*2° THEN GOTO S00 

135 IF n$="°3° THEN GOTO 610 

140 IF nhs<>°1°* THEN GOTO 120 

150 REM Read a record 

160 INPUT "Record nuaber*in 

163 REM File size limited to 65535 records 
170 IF n>65535 OR n<i THEN GOTO 160 

180 INPUT a¢13a$3AT no 

190 CLS 

200 PRINT AT 453¢°Name!t °33$( TO 30) 

210 PRINT AT GrOs "Address: *3a6(31 TO 60) 
220 PRINT AT 12923°Phonet °5a$(61 TO 75) 
230 PRINT AT 16923 *Notes! °328(76 TO) 
240 INPUT “Enter to continue’ ths 

250 GOTO 120 . 

500 REM Write a record 

510 INPUT “Record nuaber °in 

320 IF n>65535 OR n<i THEN GOTO 510 

$30 CLS 

340 DIM n$(30)% DIM bS$(30)% DIM p$(15)3 DIM c$(25) 
350 INPUT *Naee “ins 

560 INPUT “Address ‘ibs 

370 INPUT *Phone ‘ips 

560 INPUT “Notes "ics 

590 PRINT K8Lind+b6+p$+cSIAT no 

600 GOTO 120 

610 CLOSE @m1% PRINT °Finished* 


LINES 909959110 ere used for the error trapping. It is not 
possible to DIM = an existing file name. The second time through 
the programmer an error would stop the prograaner these lines 
prevent this. See Appendix £ 

LINE 115% Opens the file ‘address.dat® as s random access file 
with a record length of 100 (2356 maxiaua) 

LINE 1702 Is the system lisits noraally 2 lower limit would apply 
LINE 1808 Read from the disk the record n (8¢ will need slicing) 
LINE 390% Writes the record to the diskras a single string 

LINE 6103 The file must be closed. Otherwise records will not be 
updated. 


The BASIC prograsme covld be sore sophisticated, the point here is 
to demonstrate the way that the TOS commands are used. 


Specific records are written or read according to the number 
following the AT statesent. Access times to specific records can 
be auch shorter than with sequential type files since to access 28 
tecord it is not necessary to read through the whole file. 
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Please note the following points! 


1 - When a record is input from s filer the different fields can 
be separated with the string slicing function (T0). 

2 - Care must be taken when writing to s record because if yov 
specify a record number past the end of file the file size is 
increased until the record belongs to the file. 

3 - The record nuaber aust be an integer between 1 and 65535. 


The following is the complete syntax for the two commands! 


PRINT s@n3 Str-exp CRAT Pp? 
INFUT m@n3 Var C3AT pl 


n - channel number (1 to 16) 

Str-exp - any string or string expression resulting in » string 
with no sore than 256 characters. 

Var - any string variable or one dipensional string array 

Pp - record number (1 to 65535). Options) when using randoa 

access files. If not defineds the next record position is 

used. 


A last point! everything said about sequential files is slso true 
when using serial channels since TOS trests both in auch the sane 
waye 
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Tne RESTORE ® instructions whose syntax ist 
RESTORE £@ channel-nuaber 


Allows you to reset the file pointer (to the value 1) bringing it 
beck to the beginning of the file. This is especially useful in 
files open as streass which can only be sccessed sequentially, 


By using this cosmand when the file is open in input only (1)» you 
will start reading. the beginning of the file again. 

If the file is open in write only or append aodes you will start 
overwriting it. 

This instruction allows you to update only the initisl characters 
of a stream file without destroying the rest of the file. Only in 
output mode does it destroy sll the file contents. 

Open the file in the sppend mode and then use the RESTORE = 
instruction: you can now start rewriting the file from the 
beginning without destroying all its contents. 

The process is the same for record files» slthovgh you can avoid 
the use of RESTORE & by always specifying the number of the record 
you wants they can also be accessed sequentially. 
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CLOSE @= 
Se 
hen vou finish accessing e file you must close it. This is done 
with the CLOSE @" instructions whose syntax is? 


CLOSE @uCchannel-nusber) 


(Note that the °@* is printed by the SPECTRUM as part of the CLOSE 
keyword.) 


If you specify a channel numbers you will only close the 
corresponding channel (and associated file). If you omit itr all 
the open chennels are closed. Closing s file (or SCP) implies 
disassociating it from a channel. 

Howevers if the sode is other than input only» there is sore 
involved. 


Disk files sre described by a few bytes in the disk directory 
containing the nese of the files its size and s desctiption of 
which disk blocks (1K byte each) contain data belonging to that 
file. Thereforers if the file was open in 2 write eode (ovtput 
onlyr random or append)s the CLOSE @™ instruction aust updete 
these bytes to reflect the new file contents. 


The way in which CLOSE @¢= does this depends on the mode in which 
the file is open. NOTE that data written into a file is NOT safe 
until you CLOSE that file. If something happens (e.g. 3 power 
failure) before the file is closed» you nay lose information just 
printed to that file. So - never keep @ file open in write eaode 
longer than is necessary. 


When you open a file in the output only acde the file size is 
initislised to zeros even if the file already has some data. This 
is because the output only aode overwrites the previous contents 
of a file. Howevers the old version of the file is not destroved 
until you close the file. 


As on exsepler open a file in the output eode only. To avoid 
destroying one of your filess copy one and work on it. Enter’ 


MOVE B°SCREEN.SCR® TO °NENSCR.SCR® 


apen it with 

OPEN @u23°NEWSCR.SCR°sO 
and now enter 

Cat = 


The °8° field shows you that the file °NEWSCR.SCR® is open. Note 
that the file *NEWSCR.SCR*» which should be 6917 bytes (being #8 
screen)s exhibits a size zero. 


The *Cur* fields which shows the currently used space in the disks 


exhibits a value that is 7k bytes larger then the sue of the 
allocated spaces of all the files. 
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This is because the old version of °NEWSCR.SCR® is still there» 
hidden by the systen,. 


If you enter’ 
LIST =€2 


you can list sdditiona!] inforastion on channel 2» open to this 
file. . 


Mote this is a fast channel. The file is open as 8 streana = in 
output only aoder has size 0 and the next charecter to be written 
will be the first. This inforaation concerns the open version of 
the file. 


You can now start writing data on the file. Try running the 
following progras} 


10 FOR n=1 TO 60 
20 PRINT #O25°a° 
30 NEXT n 


Now enter 
CaT « 


File °NEWSCR.SCR® now has 8 size of 80 bytes and an sliocated 
spsce of ik. The ‘Cur® field has been incremented by one due to 
the ik block allocated to the open version of *WENSCR.SCR®. This 
peans that the CAT ® instruction follows the developaent of the 
filer sillowing you to monitor its growthr as does the LIST x¢ 
instruction. 


Enter 
LIST =@2 


Now let us siaulste a power failure. Press the reset button of the 
disk controller. This resets the entire systea. Now enter? 


LIST 2 
The fact that there sre no channels open does not mean that they 
have all been closed. The tera used here is *sborted®’s meaning 
that your work on the open files (*NEWSCR.SCR®) is lost. To better 
understand thiss enter’ 

CAT 8 
The file "NEWSCR.SCR® is still therer with a1] its 6917 bytes - so 


you didn't lose the old version of the file - but you did lose the 
@0 bytes (ik) used in the new version of the file. 
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Now do it properly. Run the prograa? 


3 OPEN €=23*newser.scr*io 
10 FOR n=1 TO 80 

20 PRINT 2823°%a° 

30 NEXT n 

40 CLOSE #22 


Now enter? 
CAT & 


Now the file ‘NENSCR.SCR* has size 80 and the ‘Cur* field is 
consistent with the sum of the allocated spaces of all the files 
of disk. Before running this program the value shown in the *Cur® 
field was 6k saaller, which proves that the old version of the 
file (which occupied 7 Kbytes) was erased. 
This was done by the CLOSE @2 instruction. 


The sane principle applies to the other write modes (randoms 
access and sppend) with information written beyond the end of the 
file when it was opened. 


This is the case with sppend in stream files»: and append and 
random access in record filesse when specifying a record nuaber 
greater than the last ane on file. Im such 8 cases a system reset 
will lose 311 new information. Howevers if you write over already 
existing inforastions this is innediately replaced and will not be 
lost even in @ power failure. This is also true with the RESTORE = 
instruction when in the append aode with streae files: and sppend 
and randoe access with record files» if you specify an already 
existing record nuaber,. 


In the input esode data is never lost (even if the power fails) 
because the file is not being updated. 


If you are writing into files slways check thet all files are 
closed before turning off your systems otherwise new information 
written in your files may be lost. : 


Errors that may occur with the CLOSE @2 instruction are : if vou 
specify a channel nat open or with a number ovtside the i to 16 
tanger TOS will print’ Channel not open and Illegal channel nuaber 
respectively. 

Extremely unlikelys but possibles is the error message! Directory 
full on disk <>» which seans the disk directory has no space to 
hold the naae and additional information of the new version of the 
file. This will only occur if you have the maxiauea possible nuaber 
of files (128) per side of the disk occupied, 


ma PP EP SE ED 


FAST ANDO SLOW CHANNELS 


SC a SS CE TD 


TOS provides you with 16 channels thet are divided into two types? 
fast end slow. Channels 1 to 4 sre fast snd 5S to 16 are slow, 
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FAST AND SLOW CHANNELS 

err rr 
TOS provides you with 16 channels that are divided into two types’ 
fast and slow, Channels 1 to 4 sre fast and 5 to 16 sre slow. 


The difference is due to menory limitations! Each fast channel has 
a 512 byte buffer exclusively reserved to it wheress slow channels 
share a common 512 byte buffer. 


TOS uses these buffers to speed up access to the disks. Reading or 
writing a memory buffer is auch faster than reading or writing the 
sane nuaber of bytes in the disk. Sor when you read a single byte 
from a files TOS reads a lot more (256) into the channel memory 
buffer. 


Slow channels share a comaon buffers and the data in that buffer 
belonging to s file can be destroyed by the data of another file 
open in another slow channel. 


When writing into a slow channels TOS writes the data in the disk 
(or SCP) immediately after the PRINT «@ instructions because 
otherwise a second PRINT 88 in another slow channel would 
overwrite that data. As ea direct consequences TOS aust perform @ 
disk access (in case of disk files) for esch PRINT =@ instruction 
(even if you only print one character)» which slows down the 
printing process. Hence the ‘slow channel® designation. 


You can observe this with the following progreal 


Enter! DIM B°FILE1® as a direct command 
10 LET n=4 
20 OPEN @uni'filei’io 
30 FOR i=1i TO SO 
40 PRINT "@n3°abcd* 
SO NEXT i 
60 CLOSE @¢8n 


which stores the sane string in “FILE1® 50 tines .Ndw run the sane 
programme with line 10 modified to sake n=5 (channel S is slow) . 
The execution time is auch longer because TOS accesses the disk 
every tine line 40 is executed, 


In reading operations this difference in speed does not arise 
unless another slow channel is used between two input operations. 


-In this case the data in the slow channel cosson buffer eay be 


destroyed forcing TOS to re-read the file, 


Before moving to CHAPTER 6 lets CLOSE @s channels that aay be open 
due to the exaeples of CHAPTER 5. 
CLOSE @= 


Closes sll channels. : ‘ 
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CHAPTER 6 


Serial comaunication ports SCP’s 


Your Floppy Disk Controller is equipped with two &S232C Serial 
Comaunication Ports (SCP‘'s). 


These RS232C interfaces are referred to ast 
*CH_A.SCP® 
*CH_6.SCP* 

Entering the following will denonstrate this! 


CAT m°3° 


SCP's are a special kind of file that convey data instead of 
storing it. Data is transmitted or received in s serial fashions 
one bit at a tise. TOS uses software and hardware protocols to 
ensure that the transmitter only sends data when the receiver is 
ready. 


The instructions used to exchange information with the outside 
world via SCP's aret SAVE Be LOAD Be MERGE =» MOVE Br PRINT & and 
‘INPUT x. 


SCP CONFIGURATION (FORMAT =) 


Comaunication between two computers (and/or peripherals) through 
an KkS232C interface is only possible when they use matching 
protocol. To perait a wide range of protocols, TOS provides an 
instruction to set all the parameters to the required values. | 


The syntax of this instruction is! 
FORMAT = SCP - pathnane 


which is distinct from the disk formatting instruction because the 
*TO° and the disk name are missing. As with eny instruction using 
8 pathnasers you can either start at the root (i.e. FORMAT 
m"SCH_A.SPC®) or you can start at your disk directory. 
Enter! 

FORMAT #°?CH_A.SCP° 
The type SCP is optionals so you could enter! 

FORMAT =°3CH_A® 
TOS proapts for the required values to be entereds but as default 
uses predefined setting. If you press ENTER» TOS proceeds to the 
next question and aaintains the previous valve for that paraseter. 
If you press SPACEr T0S terainates the command and saintains the 
former values for the subsequent paraseters. If you press a key 
that is neither ENTERe mor SPACEs nor any of the alternatives 
asked by the questions TOS repeats the question. Replies aay be 
entered in upper or lower case. 


When FORMATting a8 serial port, these are the questions asked! 
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Text or Bytes (1/8) ? 
If the data type is text answer °T® this will 
set bit 7 of every transmitted data byte to 0. 
If the data tvpe is bytes» all data is 
transmitted without modification. 


Auto line feed (Y/N) ? 
This question sppears if the data type is text. 
Answering yesr TOS will insert a line feed 
(ASCII code OAH) after each carrisge return 
(ASCII code ODH). 


XON / XOFF (Y/N) ? : 
Choosing this option TOS establishes 2 software 
protocol using two special control characters’ 
X ON (ASCII code 11H) enabling trensaissions and 
X OFF (ASCII code: 13H) disabling transmission. 


Input with wait (Y/N) ? 
Answering nor all read operations to the SPC 
will return even if the requested data is not 
presents es TOS won't wait for data to in the 
channel buffer. This is somewhat similar to the 
INKEYS function provided by the SPECTRUM, 
Otherwise TOS will wait for the requested date. 


Baud rate (A-P) ? 
This parameter determines the nueber of 
transmitted bits per seconds the transmission 
speed. The correspondence between letters and 
baud rates is! 


Letter Baud rate (bits/second) 


30 
73 
110 o 
134.5 
150 
200 
300 
600 
1.200 
1.800 
2.400 
3-600 
4.800 
7.200 
9.600 
19.200 


VOZZCZLHTONMOODD 


Parity (E=Evene O=0dds N=None) 7? 


This is an error detection nechanisna that uses 
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a bit to make the ruabers of 1's odd (0) or even 
{E). The mechanism can be disabled (N),. 


7. Stop bits (A=1+ B21.55 C=2) ? 
This is the miniaal nuaber of bits between the 
end of one byte and the beginning of the next. 


8. Bits/char (A=S- B=ér C=7> D8) ? 
Number of bits of each data byte. Although the 
noraal value is Gesome equipaent uses less bits. 
Possible values are 5S» 6% 7+ and 8. 


The factory default setting is! 


Bytes 

No auto line feed 

No X ON / X OFF 

Input operation with wait 
1200 baud 

No parity (none) 

1 stop bit 

8 bits per character 


BNO ULAWN& 
Ce | 


The new setting values defined by the FORMAT « will be destroved 
when you turn vour sytem off or press the Disk controller reset 
button. Howevers you can emake these new values permanent by 
formatting eo disk after configurating the SCP's. This will store 
the operating system (TOS) in the disk with the current SCP 
configuration. 


If you don't like the names °CH_A® and *CH_B"s you can change thea 
with the LET = instruction. 

Notes howevers that it is the disk inserted in drive A that 
provides the operating systesa. So if you want to use your own SCP 
configuration - instead of the factory default systema - you aust 
use this new disk in drive A. Or run the the utility LOSYS in a1] 
existing disks (see appendix c). 


You cannot configure an open SCP. If you doe you will get the 
error sessage! 

<> is open 
The angle brackets representing the name of the SCP in question. 


nh RP A ES 2 PRC A PR SS A SAT A a AS 
TRANSMITTING FILES THROUGH SCP‘'s 
as csv 
There are four instructions to exchange files! SAVE =» LOAD xy» 
MERGE &+ and MOVE x. 

They all work as the disk files do. The SAVE = instruction sllows 
you to transmit s program: code or data currently in memory. LOAD 
B and MERGE © perforea the inverse operation. Note the auto run 
facility is also available e.g. SAVE =°:CH_A* LINE 10. 


MOVE & allows you to copy a disk file to an SCP (or vice-versa) or 
an SCP to another SCP. 


The SCP's used aust be configured with the dats tvpe ‘“bytes’r 
since the data type ‘text® gives special interpretation to some 
codes. TOS does not check this. These instructions deal with whole 
files. To transeit or receive byte by byte the PRINT = and INPUT & 
instructions aust be used. 


SCP's sre interpreted by TOS as noreel files with special 
characteristics. Thus» you can also access SCF's with PRINT = and 
INPUT ® instructions. To do so you have to open and close the 
SCP's. 


OPEN @=z 


The syntax of this instruction is! 


OPEN @zchannel-nuaber }S8CP-pathnane! sodesrecord-length 


Using SCP‘s the randoms sccess sode (r-input or output) has s 
special seanings since each SCP can transait and receive. This 
mode means you can transmit by writing with PRINT 8@ or receive by 
reading with INPUT x@. 


As SCP's have no permanent data (SCP's send data - they do not 
store it) the append sode is given ae special meaning. For 
instances if you enter? 

OPEN @213*tche*ta 


This means thet “°CH.A.SCP® will be open in the ovtput only aeaoder 
with the data type ‘text*s the suto line feed and X ON / X OFF 
options independentely of the first four parsneters of the SCP 
configuration settings. 


In all other sodes the SCP is prograamed with the setting it had 
when vou opened it. 


As the append aode has this special neaningr there is no need to 
specify s record length. If you do TOS prints the error sessege! 
Illegal aode/type combination 


Also you cannot use the random access node (input and output) if 
the X ON / X OFF protocol option is ons because one way (transait 
or receive) of the channel is needed to transmit the X ON and X 
OFF control characters, and it therefore cannot carry data too. If 
vou have an SCP configurated to support en XON / XOFF protocol and 
try to open it in the random access aoder TOS will generste the 
error message! 
Illegal node / SCP configuration 


The same message is issued if you try to open an SCP and specify e@ 
record length when the SCP is configured with the dats type 
"text*. This is because words have a variable length. 

You cannot open an SCP input or random access in 8 slow channel 
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6.6 


You cannot open an SCP input or random access in a@ siow channel 
because the system say need to use the slow channel comaon oduffer 
to access another slow channel before it reads and stores all the 
bytes received by the SCP. 


This is no probleas with disk files because even if the bytes in 
the buffer are destroyed the disk file can be read back. SCP's dq 
not have a menory and the bytes are only received once. In output 
only or append aodes this is no problem because SCP's transait all 
the information as you write it with the PRINT & instruction. 


Sor if you try to open an SCP in the input only or random sccess 
eodese TOS will generate the error nessage; 
Cannot use 8s slow channel 

Unlike disk files» you cannot open an SCP in more than one channel 
(even if the mode is input only) because data read from an SCP is 
no longer available for another read operstion. This is because 
SCP*s have no saeaory. If you could read an SCP from more than one 
channel the bytes received would be dispersed among those channels 
and no channel would receive the whole information. 


If you try to open the same SCP in more than one channel you will 
get the error message! 


<> is open 


CLOSE ¢@= 


The CLOSE @x instruction is no different from the disk file CLOSE 
@x instruction except when the SCP is open in one of the write 
eodes and with the data type ‘text*. 


In this case an end of file character (“Z»ASCII code 1AH) is sent 
through the SCP to infore the other party that no sore data will 
be sent through the channel. 


LIST =@ 


This instruction lists information on open channels and has a 
different presentation with disk files and SCP's because the 
information to be displayed is different. 


With SCP's the information listed includes! 


Ch - Channel nuaber (1 to 16) 

T - Channel typet slow (8) or fast (F) 

M - Mode! IsOreR or A 

Typ - Typet stream (STR) or record (REC) 

Rin - Record length - nuaber of bytes of each record 
Baud - Baud rate - 50 to 19200 baud 

Dat - Data type - Text (TXT) or bytes (BYT) 

A ~ Auto line feed - yes (Y) or no (N) 

X - XON/XOFF protecol - ves (Y) or no (N) 

W - Wait on input - ves (Y) or no (N) 
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hh ssa srs thrusts hss 
RESTORE = ; a 
See ee re 
If the SCP is open in input only or random access poder this 
instruction flushes the input buffers erasing 2ll bytes in the 
channel buffer waiting to be read. 


If the SCP is open in another aode this instruction has no effect. 


APPENDIX A - ERROR MESSAGES 


This appendix includes the list of all the error codes and the 
messages which the system generates, To help you discover why the 
error arose a list of reasons is given below for each of the error 
nessages,. 

The syabols <> are used to represent a nase output by the systea 


ILLEGAL PATHNAME 


- A character with ASCII code ovtside the range 32 to 126 

more than 64 characters (including spaces) 

no characters besides spaces or no characters at all 

spaces between two characters where neither of the characters is 
@ separator (8%. *#° or *.°). 

@ filenene with sore than @ characters or an extension with sore 
than 3 

aonase and/or type without characters (spaces do not count) 

a file nase with sore than one °.° 

two colons (°%°) together 

an up arrow (°¢°) and s colon (°%*') together 

an up arrow preceded by a character other than an up arrow 

a template character (°+° or *?7°) not in the last file namerthat 
igs a colon after a teaplate character 


WON EXISTENT PATH 


- A pathnane beginning with up srrows tried to go higher than the 
root. Either you used amore up srrows than you shovid or your 
current directory is not as low as you thought. 


ILLEGAL USE OF A ROOT NAME 


- You cannot specify (1) the root or (2) a name in the root 
(disk naae or SCP), This error can occur in the following 
instructions that have a pathname as their srgquaent! 

(1) All except GO TO =» GO SUB & and CAT & 
(2) DIM w, ERASE & and SAVE = 


Bllowed. This error can occur in the following instructions! 
(1) GO TO =» GO SUB & and FORMAT = (SCP and disk) 

(2) OPEN @2, MOVE Be FORMAT & (SCP)s LOAD & and MERGE x 

(3) GO TO Be GO SUB BrATTR Be and FORMAT © (disk) 


<> OOES NOT EXIST 


- You specified a pathname in which a name (not necessarily the 
last one) does not exist. Note that this does not sean that 
the nane does not exist in your systea! it just means that it 
was not found in the path specified in the pathname. This error 
can occur in all the instructions requiring pathnamess except 


ay 
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38 


39 


40 


41 
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DIM = snd FORMAT = (disk). 


<> ALREADY EXISTS 


- You tried to create a nane that slready exists. This error ca 
occur in the DIM mw» LET & and MOVE ® instructions, 


«4 
< 
v 
m 
o 
o 
[=] 
z 
So 
«4 
> 
o 
2 
m 
m 


- This error occurs in LET = if the type (files directory or SCP) 
of the second pathname does not agree with thet of the first. . 
LET 2 can only change the namer not the type. 


~ 
m 
x 
ad 
Fr 
> 
~ 
m 
z 
So 
= 
> 
- 
= 
oS 
= 
m 
{~] 


~ You must use a nase not a template. Teaplates are only allowed 
in ERASE a» MOVE Be (only in the first pathanae)s CAT 2 and ATTR 


z 
o 5] 
n 
Lo] 
C 
m 
a 
=z. 
> 
~ 
a 
= 
- 
z 
o 
+ 
= 
m 
~« 
mi. 
x 
vo 
eC 
> 
=~ 
nm 


- You specified ae teaplate correctelys but there were no files (or 
directories or SCP's eetching it). This error can eccur in the 
ERASE =» MOVE me CAT & and ATTR = instructions. 


i] 
Load 
4 
m 
oa 
«4 
So 
2 
< 
nv“ 
¢ 
rc 
r 
o 
z 
i~] 
ad 
a 
x 
A 
Vv 


The system tried to creste or update a file but there was no 
space in the disk directory. This error can occur in the DIM ky» 
CLOSE @, MOVE = and SAVE & instructions. 

The disk directory can hold 128 entries. The disk itself vuses 
one entry for its name. Other directories slso use one entry,s 
and files occupy one entry per esch 16K in size. Thereforer a 
file with 7K uses one entry and 2 file with SOK uses 4 entries, 


o 
4 
n 
Rx 
A 
v 
nn 
ce 
| a 
ce 


- The disk has ho sore space. This error say result from SAVE > 
MOVE = or PRINT ® instructions. 


NO ROOM FOR FILE IN CHANNEL <> 


- This error occurs in the PRINT 2@ instruction with » file open as 
@ record filer with a record number so high that it would 
increase the file size to a value beyond the free space in the 
disk. With this error the disk maintains its free space, 


<> IS WRITE PROTECTED 


- You tried to update or erase s file or directory that has been 
protected by the ATTR &® instruction. 
MOVE & 


This error can be generated by the SAVE as ERASE > 
and OPEN @= instructions. : 
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file or directory defined ina disk that has been write 
protected by software with ATTR =. This error can be generated 
by SAVE Bs OPEN $x» CLOSE @a» DIM Bs ERASE up LET me MOVE Be 
PRINT = or ATTR EB. Note that the FORMAT = (disk) does not 
generate this error because this instruction formats a disks 
even if it software write protected. 


DISK <> IS HARDWARE W/P 


- The disk is hardware write protected by the write protect tabs. 
The FORMAT © (disk) instruction will not format a hardware write 
protected disks but generates the error *harduare favit on disk 
<>° instead. 


You aust erase the lower level directories first and then 
proceed upwardss erasing all the directories until you can 
finally erase the one you want. This error is generated by the 
ERASE & instruction. 


<> HAS FILES OFEN 


- You cannot erase a directory that contains open files. You aust 
close sll files defined in the directary. before you can erase 
it. This error is generated by the ERASE # instruction. 


<> HAS FILES W/P 


- You cannot erase, a directory that contains write protected 
files.You must unprotect thea with the ATTR = instruction before 
you can erase the directory. This error is generated by the 
ERASE = instruction. 


CANNOT ERASE CURRENT DIRECTORY 


- You cannot erase a directory if it is your current directory. 
Change it with GO TO x. This error is generated by the ERASE = 
instruction. 


- You can create up to 15 directories in each side of each disk. 
This error is generated by the DIN & instruction if you try to 
create eore. The structure of the directory tree does not 
matter, : 


$1 
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ILLEGAL DIRECTORY SPECIFICATION 


- This error is generated by the LET = instruction if the first 
and second pathnsees specify names (files: directories or SCP's) 
defined in different directories, 


DIRECTORY STACK OVERFLOW 


- The directory stack has only & levels. This messege appeare if 
you execute es GO SUB & instruction at level 8. 


CANNOT RETURN FROM LEVEL 0 


- You execute a DRAW 8 instruction while st level 0. Probably 
DRAW = without ae CO SUB #. 


CHANNEL BUSY 


- This error is generated by the OPEN @= instruction if you specify 
the nuaber of a channel thet is already open. Change the 
channel nuaber or close the other file first. 


CHANNEL NOT OPEN 


- You tried to execute CLOSE @m, LIST 2@» PRINT 6. INPUT 26 or 


- You specified a channel nuaber outside the range i to 16 in one 
of the following instructions! OPEN @2, CLOSE @a-¢ LIST 20, PRINT 
@#x, or RESTORE «@. Possibly s variable with » wrong value, 


NO CHANNELS OPEN 


- You executed a CLOSE @m without ergument (close sll channels) but 
all channels were already closed. This message also sppesrs in 
the LIST s# instructions but constitutes no errors just an 
inforsation report. 


NO CHANNELS FREE 


- This error message is generated by the instructions that eccess 
files as a wholer that ise SAVE ms LOAD ms MERCE = and MOVE x. 
The three first need one channel snd HOVE & needs two. This 
error occurs if there sre not enough free channels. 


NO FAST CHANNELS FREE 


- This error can only occur when trying to copy sn SCP to a file or 
another SCP. SCP's can only be read using fast channels. The 
MOVE & instruction also issues this message if channels 1 to 4 
are busy. 
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CHANNEL TABLE OVERFLOW 


The -channel table holds information on open channels and has 
capacity of 128 entries. SCP’s use one entry each. Files use one 
entry per 16K in size (an empty file uses one entry). This 
error occurs if TOS tries to exceed this nusber of entries. 
Closing a channel relesses space in the table. This error can be 
generated by SAVE BeLOAD ZeMERGE zs OPEN @m, MOVE = and PRINT x, 


ILLEGAL MODE/TYPE COMBINATION 


- This error expresses an incompatibility between the eode and 
type in the OPEN 6m. It will occur in the following situations? 

- (1) - opening a8 disk file in randos access mode (r) without 
specifying the record length. 

- (2) - opening an SCP in append mode (3a) and specifying a record 
length. 


ILLEGAL RECORD LENGTH 


- You specified a record length in the OPEN @2 instruction that is 
outside the range 1 to 2564. Any varisble used in the 
instruction aust be within this range. 


CANNOT USE A SLOW CHANNEL 


- You cannot open an SCP in input or random access ode an 
specify » slow channel. Use s fast channel. 


< > TS OPEN 


You tried to open a file or SCP» but it was already open 
another channel. You can only open a disk file in sore than one 
channel if the aode is input only. This error is generated by 
the OPEN @a» but it can slso occur in the SAVE mz» LOAD «sMERGE = 
and MOVE &® instructions which open files and SCPs to access then. 
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- You replaced a disk but the old one had at least one file open. 
You aust replace the old disk to close the file(s) before 
using 3 new disk. 


CANNOT FORMAT WITH FILES OPEN 


- This error occurs in the FORMAT & (disk) instruction if you have 
at least one file or SCP open. You aust close all files before 
formatting a disk. 
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ILLEGAL DRIVE NAME 


- This error occurs in the FORMAT @ (disk) instruction if you 
specify anvthing other than As Br Ce or D (upper or lower case) 
in the first string. These sre the legsl drive nasesr spaces sre 
ignored. 


_ ILLEGAL DISK NAME 


- This error occurs in the FORMAT = (disk) instruction if you do 
not specify a singles tegsl name in the second string. You aust 
specify a disk names that ise a directory nane not e pathnere. 


BUFFER FULL 


- This error occurs in the INPUT &@ instruction when reading froe 
an SCPe if the channel buffer dbecones full - date incoming rate 
greater than systee throughput - and you have no protocol to 
stop the transaitter. Configure the SCP to sppropriate protocol, 


SCP I/0 ERROR 


- A transsission error was detected when reading from an SCP. 


ILLEGAL OPERATION ON READ FILE 


- You executed sas PRINT 2@ instruction with es channel nuaber 
corresponding to a file or SCP apen in input only. 


ILLEGAL OPERATION ON WRITE FILE 


~ You executed sn INPUT &$ instruction with e@ channel nuaber 
corresponding to a file or SCP open in output only or sppend. 


- You. executed an INPUT 24 instruction in a channel corresponding 
to a file whose pointer was at the end of the file. Wo dats is 
read. 


HAROWARE FAULT ON DISK < > 


- This sessaege can be generated by any instruction that reads or 
writes from or to the disk. A hardware fault may be detected, 
either from the disk itself or the drive. A likely cause is 
that there is no disk in the driver end note the systen does not - 
work unless there is 2a disk in drive A. 
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OISK CORRUPTED 


This message appears if either! 

(1) - The disk is partially destroyed through sagnetic fields» 
heat etc. 

(2) - Your operating systea loaded in mesory is corrupted: due 
to noises caused by electrical interference. 

(3) - You have replaced the disk in drive Are and the new disk 
has 2a different version of the operating systenm TOS. 

You should reset your system. If the nessage persists, then the 
disk has become corrupted. In most cases you should be able to 
recover all or sost of your files from the faulty diskr by 
copying thea onto a good disk. 


ILLEGAL DATA TYPE 


- This error occurs in the LOAD = instruction if you specify an 
option (CODEs SCREEN»e DATA or nase) that is not the same or 
compatible with the aption of the SAVE & that created the file. 
This error is also generated if you try to load a file not 
generated by SAVE = or MERGE & - a file that does not contain a 
BASIC prograane, 
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APPENDIX & - TOS summary 


This appendix presents a brief description of each one of the 
extended BASIC instructions provided by TOS in alphabetical order. 
For references 

The arguments between square brackets are optional. 

<> are used to represent s disk nane/ nuaber/file/ or pathnare 
output by the system, 


Syntax! ATTR # pathnase FP or U or I or Vv 


The P or U Protects or Unprotects s file respectively whereas I 
hides a file from the CAT EK display and V unveils it. 

Protected files sre recognized by the appesrance of a P under the 
rightmost field of the disk directory. If the file is unprotecteds 
this field appears blank. Obviously neither ‘V' nor ‘I' will ever 
be displayed under the status field. 

The pathname can be a teaplates so you can protect (or unprotect) 
shide (or unveil more than one file with the saee command. 

A protected file cannot be erased or written to. If you protect a 
disk» then you cannot write to that disk. Note that the FORMAT = 
instruction can destroy a protected disk. 


CAT «® 


Syntax: CAT & Cpathnane) 


Without the pathnamer this instruction displays information on all 
the files defined in the current directory. If the argument is 
specifieds only the information concerning the files designated by 
the pathname (which can be a template) is Listed. 

This information consists of 


(1) General Data 
1 - Pathname of the directory where the files are defined 
2 - Its level 
3 - The nase of the drive where it is physically defined 
4 - The disk capacityr the currently used space and the 
remaining spacer all in K bytes. 
2) File Specific Data 
1 - Name (including type?) 
- Size in bytes 
- Real size in K bytes (the space actually used) 
- File status (open or closed) 
- File protection state (write protected or unprotected) 


“~ 
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As @ special caser executing this instruction in the root shows 
the physical resources of your systems that iss the disk 
currently used and the SCP‘s,. 
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CLOSE ¢z 


Syntaxt CLOSE @= expression 


This instruction closes the open file linked to the channel nuaber 
given by the expression. ° 

The channel is disassociated from the file and becomes free. 

If the file was open for input only» it suffers no aodificsation. 
If the file was open for ovtput onlys or for random access 
Cinput/output) or appends this instruction updates the file with 
the aodifications aade to the file. If the system is initialized 
(by pressing the reset button or switching it off and on) the 
previous version of the file (prior to the OPEN @ instruction) 
will remsin unchanged. The asodifications made will only be 
transferred to the disk after the CLOSE @= instruction. 


MOVE «= 


Syntax? MOVE = source-pathnane TO destination-pathnase 


This instruction copies a file or SCP to another file or SCP. The 
source is not destroyed nor modified. The following combinations 
sre sllowed ti. Copying » file to a file makes a file duplicate 
allowing you to produce backup copies. 2. Copying an SCP to a file 
3. Copying es file to an SCP. 4. Copying an SCP to an SCP. 

The source-pathname can be s teaplater allowing vou to copy 
several files with a single commands but in this case (and only in 
this case) the destination pathname aust be a directory. All the 
files eatching the teaplate will be transferred to this directory? 
unless an error occurs. 


TOS prints the nases of the files (or error messages) es they sre 
being copied. 
SCP's cannot be used if vou specify a teaplate. 


OIK «= 


Syntax? DIN = pathnane 


This instruction creates a file or a directory specified by the 
pathname. If you want to create s directoryr you aust specify a 
nase with the type °“DIR®. Without its TOS will create a file. 
Files sre created with size 0 and newly crested directories are 
eapty. SCP’s cannot be created. 
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ERASE = 


Syntax! ERASE = pathnane CN) 


ERASE * erases files: that iss destroys thes end removes their 
nanes from the directory where they are defined. 

The pathname can be a tenplater so you can erase nore then one 
file with a single command. 


This instruction will generate an error if you try to erase s file 
or directory that is write protected or belongs to s protected 
disk. 

TOS asks for @ confirmation of erasure with the question’ 


Erase <> (Y/N)? unless an °n* is specified in the initial coamand 


FORMAT & (disk) 


Syntax: FORMAT & drive-nane TO disk-nane 


The FORMAT = instruction forrats the disk currently inserted in 
the drive specified. Note that you aust specify the name of the 
drive (As Br C or DD)» not the pathnane of the disk. 
CAUTIONS This instruction destroys all the files contained in the 
disk. The software protection provided by ATIR = is not effective. 
The only way to protect a disk against formatting is to protect it 
by hardwarer using the disk's protection tabs, 
Since this is a dangerous instruction (even sore so than ERASE =)» 
TOS checks your request before formatting by printing’ 
Format disk in drive <> (Y/N)? 
Typing N will’ abort the coanand 
If you specified drive A» TOS will print an additional sessage! 
Change diskette and press ENTER 
and waits for you to press the ENTER key before proceeding. 
This allows you to format disks (without destroying the disk you 
are using)? even if you have only one drive (which is necessarily 
drive A). 


FORMAT = (SCP) 


Syntax! FORMAT = SCP-pathnane 
If the string expression is 3 pathnase designating e@ SCPr you can 
change the configuration of that SCP. TOS prints the following 
questions’ Text or bytes (T / BD? 

Auto line feed (Y / N)? 

Software protocol (¥ / NM)? 

Input with wait (Y / WN)? 

Baud rate (A - PP)? 

Parity (Nenoner Ezevenr O20dd)? 

Stop bits (A=zir B=i.Ss C=2)7 

Bits/char (A=S: B=é, C=7> D=8)? 
In each case» you must type one of the letters shown sbove. You 
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can hit ENTER if vou want to proceed to the next parameter without 
changing the value of the current oner or SPACE if you don’t want 
to change any of the subsequent parameters, 


GO SUB * 


Syntax! GO SUB & Cpathname] or GO SUB x*drivenane’d 


The GO SUB © instruction saves the current directory in a special 
stacks known as the “directory stack‘. 

If the pathname is specified: then TOS changes the current 
directory to the one designated by the pathnane,. 

This instruction is used in conjunction with DRA & as an easy 
eeans of returning to the original directory - even without you 
knowing which this is. Several GO SUB x instructions can be 
nested. The CAT ® instruction shows the current level of GO SUB x 


If you use the ‘d’ parameter you aust specify the drive nene 
(ArsBeCeD) and not the pathnase .Hence you can aove to snother drive 
without knowing the disk name. Note that your directory level will 
be incremented as the stack directory is updated. 


Syntaxt GO TO & pathname or CO TO x*drivenane’d 

This instruction changes the current directory to the one 
designated by pathnaae. It is similar to GO SUB =» except it does 
not save the current directory in the directory stack. 


Similarly to GO SUB & the ‘d‘ option is available. Except that 
once aore the directory stack is not used. 


Syntax? INPUT Zé@n3 VARS CAT pl 


Reads a character(s) or a group of characters (i.e. a record) froe 
2 file or SCP vis a channel . , 


n-specifies a channel (From 1 to 16) 
VARS-Any string variable or one dimension string array. 
P-Record nveber (1 to 65535) .Used to point to next record to be 


accessed in the randos access acde. If ommited the next record is 
used. 


$9 : 


LIST « 


Syntax! LIST = 


The LIST ® instruction lists inforeation on the current directory 
and on all directories stored in the stack. 
This inforeation includes! 

1 - The pathname of the current directory 

2 - Its level 

3 - The drive where its disk is inserted 
This inforaation is partially displayed in the first two lines of 
the listing produced by CAT &. 


LIST «¢ 


Syntax’ LIST 2# Cehannel nuaber] 


If the channel number (can be 8 numerical expression) is givens 
this instruction lists inforastion of the corresponding channel. 
If the channel is not opens an error sessage is generated. 
If the expression is omitted, this instruction lists inforsaetion 
on all open channels. 
This inforastion includes? 
For the channel(s) open to a file 
- Channel nyaber 
Channel type (fast or siow) 
Mode! i - input (read only?) 
o - output (write only) 
rt - randos sccess (read/write) 
a - append (write at the end of the file) 
Type (record or stream) 
Record length (1 if stresa) 
- Current record (file pointer position) 
- Size (file size in bytes) 
Channel open to an SCP 
~ Channel nuaber 
Mode: i - input (receive only) 
Oo - output (transit only) 
t - full-duplex (transmit/receive) 
@- output of text with auto line feed and 
software protocol 
- Type (record or stream) 
- Record length (1 if streaa) 
Baud rate (50 to 19200 baud) 
Dats type (text or bytes) 
- Auto line-feed -yes (Y) or no (N) 
- XON/XOFF protocol -yes (Y¥) or no (N) 
This instruction also prints the nuaber of free channels. 


] 
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LOAD = 


Syntax? LOAD = pathnane load-option 


The LOAD # instruction is very similar to its equivalent in the 
SPECTRUM's BASIC. The load options are the sane. 

The pathnaae can represent an SCPs allowing you to receive BASIC 
prograas (or code) directly from another computer. 


MERGE & 


Syntaxt MERGE 2 pathnane 


This instruction is similar to its equivalent of the SPECTRUM 
BASIC language and emerges a disk BASIC program to a progres 
already existing in the menaory of the SPECTRUM 


LET = 


Syntaext LET & old-pathnase TO new-pathnaae 


This instruction renanes a files directory or SCP. Both pathnanes 
must designate the same directory. 
This renaming operation does not affect the protection attribute. 


OPEN @z 


Syntaxt OPEN @= expression IspathnsaeimodelCexpression 2] 


This instruction opens a file or SCP and associates a channel 
with it» allowing you to access it through the instructions PRINT 
= and INPUT &. 
expression 1 - channel nuaber 
pathnase - pathnase of the file or SCP 
mode - i ~- input (read only) 
o - output (write only) 
t - randoe access (read/write) 
a - sppend 
expression 2 - record length 


PRINT = 


Syntax! PRINT K¢niSTROs CHAT PI 


Weites cheracters or groups of characters (i.e. records) to a file 
or SCP visa a channel. 

n-Specifies channel nuaber (1 to 16) 

STRE-Any string or string expression with no eore than 256 


P-Record nueber (1 to 65535) used to point to next record to be 


accessed in the random access mode. Can be ommited in which case 
the next record will be used. 
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Syntax DRAW & 


This instruction is used in conjuntion with GO SUB = to retrieve 
directory information from the directory stack» and thus return to 
the directory that was current when the last GO SUB = instruction 
was executed. 

The directory level is decremented by one. An error occurs if you 
try to execute this instruction in level 0. 


SAVE = 


Syntax? SAVE & pathname save-option En) 


The SAVE «& instruction is very similar to its equivalent in the 
SPECTRUM's BASIC. The save-options sre the sane. 


When the optional (n] parameter is given TOS will overwrite an 
existing file with the sane filename without the usual proapting! 


<> already exists 
Supersede (Y/N) ? 


The pathname can represent an SCP» allowing you to transmit BASIC 
programs (or code) directly to snother computer. 
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APPENDIX C - UTILITY PROGRAMMES 


The deaonstration disk contains sa number of utility programmes to 
perform certain useful operations. This appendix will explain the 
use of these progranaes.They aay be found under the directory 
‘UTIL’. 

The progreeses contained sre BACKUP, DUMP: LPRINTs and LOSYS. 


BACKUP 

This programme will copy en entire disks sector by sectore copying 
all the contents.This allows the creation of backup copiess and 
will operate by copying the disk in drive A to any of the other 
drives.It is possible to copy to drive Ar in which case the prompt 
will appear to ‘change disks now’. It is neccesary to shuffle 
between the easter and the target disk until the copy is coaplete. 
Using any other drive the copy will proceed without stopping. 


Losys : 

This utility allows the updating of the operating system (TOS) 
without the loss of data in your disk. Each side of the disk has 
an operating system written to its and this utility will copy 


- across your prograsees onto e new disk with the new opersting 


systea resident. 

To run the programme? LOAD z°LOSYS*® 

Several options are offered in auch the sane way as the backup 
programmer responding to these options: you can work with drive A 
only or any one of the other three drives.This utility can be used 
after FORMAT x(scp) to change default setting on existing disks. 


DUMP . 

This will sllow the chosen file to be duaped onto the screens 
giving, the hexadeciaal bytes» for each address» and the ASCII 
equivalent. Where the ASCII character cannot be printed it is 
displayed es a. (dot). The programae will prompt you for the 
nane of the file you want to duap in this way. 

To run the prograaseiLOAD s°DUMP* 


LPRINT 
This progrense will activate your printer connected to the serial 
channel A to work with the comasnds of SPECTRUM BASIC to print 


‘text and list a programee! LPRINT and LLI8ST. 


The prograame does not use any of the sain RAM of the SPECTRUM: 
but uses the print buffer. Every tine a NEW coaesend is nade this 
progremme will be destroved. To use the progrsease it avst be 
first loadeds then run and then. line 9s which is the only 8asIc 
line of the progranser should be erased. The prograseme should be 
entered before the asain progrsase you want to user however it can 
be MERGED to the existing programaes provided no line 9 exists. 
There is a STOP coamand st the end of line 9 to allow a nerge 
followed by s GO TO 9. The GO TO 9 will activate the printing 
routine by loading the machine code required. Once the code is in 
line 9 is no longer required and should be deleted. The SsTorP 
command will stop entry into the main programae and allow you to 
break out and delete the line 9%. 
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O.1 


APPENDIX D - RS232C LINK-UPS 
La a ET I TET TS IE I IT LeU Bo I ET I I IT, 

FIN OUT OF FLUG SHEEEEEFEEHEEEEESEEESEESESEEEESE 
+ 1 2 3 4 5 + 

The &S232C sockets are + + 

wired as follows! + é 7 8 9 + 

PEEEEEEEEEEE4ES4O444444 

1 - N/C (not connected) 

2 - TX data (transmit data) 

3 - RX data : (receive data) 

4 - CTS (clear to send) 

5 - OTR (dats terminal ready) 

6&6 - N/C 

7 - Ground , (signal ground) 

8 - N/C 

9 - +12 (Pull-up) 


0.2 


MAKING a standard 25 pin D-type cable to connect a printer 
Cavailable from your dealer) 


FDO SYSTEM---- TO -------- RS232C peripheral 
connections on 
9 Pin D-type 25 Pin D-type 
Zo rrr entrees eerccce 3 Rx Data 
2 SSiscesessss wc---- 2 Tx Data 
4 Sossss- wrecen---- 3 CTS 
Soo osooscs-- wescosses> 20: 'DIR 
7, SosssSSsssses5) ---- 7 Signal Gnd. 
Fo Saass- seer cecece-= & DSR (date set ready) 


NOTE? You will need to check your printer configuration (protocol)» and 


match it with that of the FDD SYSTEM. You can use the default 

protocol(see chapter 6)» and configure your peripheral to that or 

you can reconfigure the RS232C port's current setting by using the 
FORMAT m°SCH_A® instruction. 

The most likely need will be to reconfigure the baud rate to match 

the peripheral. 


PRINTING CHARACTERS 

There is a2 utility programme named “type* which you will be able 
to use with your printers making it echo the ovtput from the 
keyboard like a type writer. This is under the directory named 
*UTIL® on your demo disk. 

Before loading the program connect 8 printer equipped with an 
RS232C interface to channel & of the controller. 


USING LPRINT snd LLIST 
You will need the utility programme “lprint® see sppendix C 
These can also pass control codes for enlarged print etc.3 
10 OPEN @n1°S3CH_Ac3 a 
20 PRINT £€13CHRS(27)4+°E* 
30 CLOSE ¢@x1 


D.5 COMMUNICATING - FDD SYSTEM to another SYSTEM 


Controller to Controller connection will use a standard 9 
Pin D type cabler to connect two FDD SYSTEMS. For any other 
systes using an R&232C interfaces follow the pin ovt table abover 
making the connections as shown. The receive programme would need 
to be written to suit that systea, 


To send characters between two systems connect the cable to both 
channels A of each systea and load RSTRANS (under directory UTIL) 
into the transmitting computer. The programse listing is as 
follows? 
Prograaset RSTRANS 

10 OPEN @n13*tch_a'ioa 

20 IF INKEY$<>°* THEN GO TO 20 

30 IF INKEY$=°* THEN GO TO 30 

435 PRINT INKEYS3 

50 PRINT wO13 INKEYS 

60 GO TO 20 


The receiver should load RSRECEIV (under the directory UTIL). 
Listing as follows! 
Programme? RSRECIEV 


10 OPEN @z15°SCH_A°3i31 

20 INPUT K¢13AS3 

30 PRINT A$$ - 
40 GO TO 20 


The receiver should start running the programs before the 
transaitter. 


You will find it easy to send prograas from one computer to 
another. Sisply load the programs you want in the transmitting 
cosputer and then type! 


SAVE x°3CH_A® or( SAVE B°3CH_B") 


Note the use of CH_A or CH_B depends on the port connections used. 
In the rest of these exaaples CHA will be used for clarity. 


The receiver should type? 
LOAD w°3CH_AS 
All the save and Load options are available (see section 3.6) 


Using the MOVE & instruction it is possible to send a disk file 
from one coaputer to another using the RS232C (SCP‘'s)» linked up. 
Example: 
sender $ ‘ 
MOVE K°File name® TO *3CH_A® 
receiver! 

MOVE m°SCH_A® TO *file nane*® 


As before the receiver needs to be active first 
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Sa a NE ETT NE SS IE NE SAN TTI, TRON, I ENE CI NE NT EE EET IE SIG AT IE EIT TOIT TOT TEE! 
APPENDIX E - Error trapping 
SRS I IIS SEL TS ONS SE PLY AEN EE RT I RH TTT IE) 


The extended BASIC instructions of TOS dealing with the disk 

drives issve an error reports where there is one- If these 

instructions are used within a programeer there is no way of 

knowing if they can be executed. For exaaple suppose a sequential 

file is being accessed and it is not known where it will end. Any 

further data output from the file will generate an error stopping 
the prograame. There are tines that this type of error needs to 

be ‘trapped's perhaps warning the user that this has heppened, but 

not having the programme stop. 


The method of carrying out this error trapping in TOS is using two 
of the unused systeas variables of the SPECTRUM: which are 
referred to as SYSERR» and TRAP. When the SPECTRUM is turned on 
it writes 0 in TRAP and never uses it againe Poking another value 
into that location will activate the error trapping sechanisa 
whereby TOS will write an error nuaber into SYSERRe when one 
occurss and a zero when there is not an error, 

Testing for the error nuaber and the error condition is the way 
that error trapping can be performed. The following exasple 
shovld explain the method more clearly! 


SO LET TRAP=23729 tLEF SYSERR=23728 
100 OPEN @21313*Filensme*’sI 
110 POKE TRAP?255 
120 INFUT RO1;5AS 
190 IF PEEK SYSERR<>0 THEN GO TO 500 
140 FRINT A$ 
150 GO TO 120 
500 PRINT ‘Reached end of file* 
510 CLOSE #x1i 


Use any “Filename® that exists under your current directory 

Line 110 error trapping is activated. 

Line 130 the error nuaber will appear in SYSERR»s or 8 0 if no 
there is not an error. The error numbers are those that sppear in 
AFPENDIX A. 

Making vse of these errors can be achieved as follows! 


500 IF PEEK SYSERR<>72 THEN PRINT ‘System = error 
nyaber* SPRINT PEEK SYSERR?$STOP 

510 PRINT °Reached end of file® 

520 CLOSE #@zi 


Note error 72 means an attempt to read past the end of a filer 
any other error will cause the programee to STOP. 


To disable the error trapping rovtine remember to poke 2372970 


APPENDIX F - MACHINE CODE TIPS 

RR A i IT EE TE TE EE IT ES TE IIE ITE I LESTE TLE IES TAI! LILLIA ILE 
The extended BASIC functions of TOS may be used in machine code 
progremaess but to do so calls aust be made to the external ROMs 
that TOS use. The first stage is to understand the ROM swapping 
sechanisa that is used. All the new coasands are in an external 
ROM that uses the sane address range of the standard BASIC ROM. 
To access that ROM it aust be selected by Jjuaping to address 
0008H. After doing this the external ROM is enabled and the 
tovtines can be vused. To avoid crashing the system and not . 
losing control of your programmer it is suggested that you use 
the following code to switch ROM's! 


PACEIN PusSH IY tthe ROM uses IY to detect a user call 
LD _IY0 sfleg user call 
CALL 6 Spaging sechanisea sctivated 
Pop Ivy Srestore IY 


NOTES? 1 -After executing PAGCEIN the external ROM disables 
interrupts. 
2 You can not use BASIC ROM routines using CBAS. CBAS is 
explained later 
3 -You have sccess to iKbyte of RAM from 2000H to Z23FFH 
that is used by the systee to store variables and 
buffers. It is free from 2156H to 23FFH. 


After using the external ROM you can reselect the BASIC ROM by 
calling 0603H or 0604H» the latter does not reenable the 
interrupts. 


In the external ROM there is se routine to call rovtines in the 
BASIC ROM with the external ROM selected, that takes care of sll 
switching, It is called with the address of the BASIC ROM in the 
next two bytes. For exsaplet 


CBAS EQU 061DH tthe special calling routine 
CLS EQU OD46BH tthe spectrua routine 


CALL CBAS 


DEFR CLS tthe calling address law byte 
first 


There is 2a juap table starting at 0605H with some of the sost 
useful routines in the external ROM to the sachine code 
progranser. The following is 2 list of the routines and the 
calling addresses! : 


0605H JF PUTDAT 


Purpose ttransfer s dats block to the disk systen 
Registers vused!inone 
INPUT $data to transfer in bufdat (2000H to 20FFH) 
A - number of bytes to send 
OUTPUT tnone 
Comment tcan be sborted with break 
0608H UP PUTCON 
Purpose tsend comaand to the disk systea 
Registers vusedinone 
INPUT tAFse BCe DEe HL» IXe LY 
OUTPUT tnone . 
Coanent tall registers are sent to the disk systen,. 
Can be aborted with break 
O60BH UP GETBLOCK 
Purpose tget data or command from the disk systea 
INPUT tnone 
OUTPUT {deta - carry reset and dats in bufdat 


comeand ~- carry set and sll the registers 
changed. Error code in 2100H and 
error message in Z210DH to 211DH 


Comaent . tcan be aborted with break 
O60EH JF SENDBL 
Purpose {send a@ package to the disk 
Registers usedinone 
INPUT . 3HL - buffer pointer 
(tvp)»s Clen) - type end length of data to send 
OUTPUT {zero if ok 
O612H JP GETBL 
Purpose Sget a peckage from the disk 
Registers usedinone 
INPUT {none 
OUTPUT Sdats in bufdst or bufcos 


zero if ok 
_ (typi, Clend) - type and length of data received 
0614H JP ROBLOC 


Purpose tread up to 256 bytes from file 
Registers usediBC» HL 
INEUT 8(chan) - channel nuaber 

DE - number of bytes to read 
BUTPUT tzero if ok 


HL points to bufdat 
EC nuaber of bytes read 


0617H JF ROMEN 

Furpose tread a file to memory 

Registers usediaA 

INPUT t(prolen) - number of bytes to read 
(prostr) - loading address 
(chan) - channel to use 

OUTPUT tzero if of 

Comment Sprolen and prostr are two byte variables 
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To send a command to the disk system you aust dani the ‘Mosmand in 


SS1AH JF WRTMEM 


Purpose twrite memory to a file 
Fegisters useat oa * x 
INPUT “$¢(prolen) - number at bytes to write 
: (prostr) - starting address . 
(chan) - channel number 
OUTFUT :zero if ok 
O610H JP CEAS 
Furcose seall a GASIC ROM subroutine 
INFUT Saddress to call 
Comment tall registers are creserved during the ROM 
switching ; 
C0620H JP —  -SAVEP 
Purpose {save code or a grogram to a file 
Registers usedinone 
INPUT *Pathname in bufdat (must end with CHRS(0)) 
. A ~ len of pathname : 


EC - len of cade te save 
DE - code start : 
! HL - line number if there is one ES 
OUTFUT : tzero if ok bers me, < eget 
x . : : Hit ” oP 2: 
To study the extended BASIC ROM you can use this prograsset 


cOFY PUSH IY oot Mae 
LO OTY,0 ee t pew cs 
CALL 9008H - ; ee) ee ee 
POF iY _etne easin reiting’: a Nes 
LO EC*1000H ithe ROM oy has “Akbytes, gee 
LD HL CO00H ae ea 
LO OE CEST ipiaie in aanore where code,(to be 

put : cA. ¢ ‘ 

LDIR - x ; ‘ 
CALL CSO3H tenders the asic ROK 4 . ate 


atts y 


tat 


2100H set the Z80 registers with correct parameters and eall 


FUTCOM. The disk tries to execute the command and sends back the 
result and error report (0 if O.K). To get the, result you can use 
GETELOCK which returns with the carry set, if” “thg,. disk sent a 
command or reset if it was data. ; : De 4 ; 


wos 


RET freturn o ae ee 


